magically 0.0.1
This tool is created for non-programmers but they know how to build algorithms then this is a perfect fit. In this tool, you have to setup 'MAGIC_API_KEY' which is a openrouter api key then you can use it freely. 
Requires Python: >=3.11
Keywords: pseudocode, vibe coding

# magically: Pseudocode Algorithm Tool for Non-Programmers

magically is a powerful command-line interface (CLI) tool designed to empower non-programmers to conceptualize, manage, and translate algorithms using a simplified pseudocode syntax. It bridges the gap between human logic and executable code, making algorithm development accessible to everyone.

✨ **Features**

* **Project Management:**
    * `magically init <project-name>`: Initialize a new magically project with a standard directory structure (`src/`, `outputs/`, `magically.config.yaml`, `README.md`).
    * `magically new <algorithm-name>`: Create a new pseudocode file (`.mg`) within your project's `src/` directory, pre-populated with a basic template.
    * `magically list`: List all pseudocode files (`.mg`) in your current project.
    * `magically delete <algorithm-name.mg>`: Safely delete a pseudocode file from your project.

* **Pseudocode Authoring & Enhancement:**
    * `magically lint <file-name.mg>`: Analyze your pseudocode for best practices and clarity, providing AI-powered recommendations for improvement.
    * `magically format <file-name.mg>`: Automatically reformat your pseudocode for consistent style and readability using AI.

* **Pseudocode Translation:**
    * `magically translate <file-name.mg> --to <language>`: Translate your pseudocode into a target programming language (e.g., `python`, `javascript`, `java`).
        * `--output-dir <path>`: Optionally specify a custom directory to save the translated code.

* **Utility Commands:**
    * `magically version`: Display the current version of magically.
    * `magically dashboard`: (Placeholder) A future feature to launch a simple web-based dashboard for project overview.

🚀 **Installation**

**Prerequisites**

* Python 3.8+
* An API key for OpenRouter (e.g., from [openrouter.ai](https://openrouter.ai)). You'll need to set this as an environment variable.

**Steps**

1.  **Clone the Repository** (or download the source code):
    ```bash
    git clone [https://github.com/your-username/magically.git](https://github.com/your-username/magically.git) # Replace with your actual repo
    cd magically
    ```

2.  **Install Dependencies:**
    It's highly recommended to use a virtual environment.

    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    pip install -r requirements.txt # Create a requirements.txt file with your dependencies if you don't have one.
                                   # Alternatively, you can list your core dependencies directly:
                                   # pip install typer rich pydantic pydantic-ai
    ```

3.  **Set Your API Key:**
    magically uses AI agents for linting, formatting, and translation. These agents require an API key for OpenRouter. Set the environment variable `OPENROUTER_API_KEY` (or `MAGIC_API_KEY` if you configured it that way) with your key:

    **Linux/macOS:**
    ```bash
    export OPENROUTER_API_KEY="sk-or-YOUR_OPENROUTER_API_KEY"
    # To make it permanent, add this line to your shell's config file (.bashrc, .zshrc, etc.)
    ```

    **Windows (Command Prompt):**
    ```cmd
    set OPENROUTER_API_KEY="sk-or-YOUR_OPENROUTER_API_KEY"
    # For permanent setting, use System Properties -> Environment Variables
    ```

    **Windows (PowerShell):**
    ```powershell
    $env:OPENROUTER_API_KEY="sk-or-YOUR_OPENROUTER_API_KEY"
    # For permanent setting, add to your PowerShell profile
    ```

💡 **Usage**

Navigate to the directory where you want to create your magically project or where your `magically.py` executable is located.

1.  **Initialize a New Project**
    Start by creating a new magically project.
    ```bash
    python magically.py init my-awesome-project
    ```
    This will create a `my-awesome-project` directory with `src/`, `outputs/`, `magically.config.yaml`, and `README.md`.

2.  **Create a New Algorithm File**
    Navigate into your new project directory:
    ```bash
    cd my-awesome-project
    ```
    Now, create a new pseudocode file:
    ```bash
    python magically.py new my_first_algorithm
    ```
    This creates `src/my_first_algorithm.mg` with a basic template.

3.  **Write Your Pseudocode**
    Open `src/my_first_algorithm.mg` in your favorite text editor and write your pseudocode.

    **Example `src/my_first_algorithm.mg`:**
    ```
    START
      DECLARE number AS NUMBER
      READ number
      IF number > 10 THEN
        WRITE "Number is greater than 10"
      ELSE
        WRITE "Number is 10 or less"
      END IF
    END
    ```

4.  **Lint Your Pseudocode**
    Check your pseudocode for best practices and get recommendations:
    ```bash
    python magically.py lint my_first_algorithm.mg
    ```

5.  **Format Your Pseudocode**
    Automatically format your pseudocode for consistency:
    ```bash
    python magically.py format my_first_algorithm.mg
    ```

6.  **Translate Your Pseudocode**
    Translate your pseudocode to a target programming language:
    ```bash
    python magically.py translate my_first_algorithm.mg --to python
    ```
    This will save `outputs/my_first_algorithm.py` (or `.js`, `.java` depending on the `--to` flag).

7.  **List Algorithms**
    See all pseudocode files in your project:
    ```bash
    python magically.py list
    ```

8.  **Delete an Algorithm**
    Remove an algorithm file from your project:
    ```bash
    python magically.py delete my_first_algorithm.mg
    ```

🤝 **Contributing**
Contributions are welcome! Please feel free to open issues, submit pull requests, or suggest new features.