Metadata-Version: 2.4
Name: educode-agent
Version: 0.1.0
Summary: Autonomous coding agent — local-first, RAG-aware multi-agent CLI
License: MIT
License-File: LICENSE
Keywords: coding-agent,llm,cli,langchain,rag,developer-tools,ai
Author: EduCode Agent Contributors
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Dist: click (>=8.4.1,<9.0.0)
Requires-Dist: gitpython (>=3.1.50,<4.0.0)
Requires-Dist: langchain (>=1.0,<2.0)
Requires-Dist: langchain-openai (>=1.3.2,<2.0.0)
Requires-Dist: langchain-qdrant (>=1.1.0,<2.0.0)
Requires-Dist: langgraph-checkpoint-sqlite (>=3.1.0,<4.0.0)
Requires-Dist: langsmith (>=0.9.0,<0.10.0)
Requires-Dist: mcp (>=1.28.0,<2.0.0)
Requires-Dist: pydantic (>=2.13.4,<3.0.0)
Requires-Dist: pydantic-settings (>=2.14.2,<3.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: qdrant-client (>=1.18.0,<2.0.0)
Requires-Dist: redis (>=8.0.0,<9.0.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Requires-Dist: sentence-transformers (>=5.6.0,<6.0.0)
Requires-Dist: tavily-python (>=0.7.26,<0.8.0)
Requires-Dist: textual (>=8.2.7,<9.0.0)
Requires-Dist: tree-sitter (>=0.25.2,<0.26.0)
Requires-Dist: tree-sitter-python (>=0.25.0,<0.26.0)
Project-URL: Documentation, https://github.com/3eyedtech-creator/educode-agent#readme
Project-URL: Homepage, https://github.com/3eyedtech-creator/educode-agent
Project-URL: Repository, https://github.com/3eyedtech-creator/educode-agent
Description-Content-Type: text/markdown

# EduCode Agent

[![CI](https://github.com/3eyedtech-creator/educode-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/3eyedtech-creator/educode-agent/actions/workflows/ci.yml)

Repository: [github.com/3eyedtech-creator/educode-agent](https://github.com/3eyedtech-creator/educode-agent)

EduCode is a local-first, RAG-aware coding agent CLI. Open any project folder, run `educode`, and work with your codebase through natural language — ask questions, generate changes, debug failures, and run validation tasks.

It works similarly to Claude Code: the agent indexes your repository, understands context via semantic search, and uses a multi-agent supervisor (planner, coder, reviewer, runner) with human approval before mutating files.

## Prerequisites

Before using EduCode, make sure you have:

| Requirement | Details |
|-------------|---------|
| **Python** | 3.11 or newer |
| **OpenAI API key** | Required for LLM calls and embeddings (`OPENAI_API_KEY`) |
| **Git** | Recommended (diffs, project workflows); not strictly required for basic use |
| **Internet** | Required for OpenAI API calls during chat/run |

Optional:

| Variable | Purpose |
|----------|---------|
| `LANGCHAIN_API_KEY` | LangSmith tracing ([smith.langchain.com](https://smith.langchain.com)) |
| `TAVILY_API_KEY` | Web search (when wired in future releases) |
| `QDRANT_URL` | Remote Qdrant; omit to use embedded local storage |

No Docker or separate vector database install is needed — Qdrant runs embedded locally.

## Installation

### End users (PyPI) — recommended

Install from PyPI with pip:

```bash
pip install educode-agent
```

PyPI normalizes names, so this also works:

```bash
pip install educode_agent
```

For an isolated CLI install (recommended, like Claude Code):

```bash
pipx install educode-agent
```

Verify the `educode` command is available:

```bash
educode --version
```

If `educode` is not found, ensure your Python scripts directory is on `PATH`:

| Platform | Typical scripts location |
|----------|--------------------------|
| Linux / macOS | `~/.local/bin` |
| Windows | `%APPDATA%\Python\Python3xx\Scripts` |

Then open any project folder and start the agent:

```bash
cd /path/to/your-project
educode
```

That launches the interactive chat session (same as `educode chat`).

### From source (developers)

```bash
git clone https://github.com/3eyedtech-creator/educode-agent.git
cd educode-agent
poetry install
```

Verify the CLI:

```bash
poetry run educode --version
```

## Environment setup

1. Copy the example env file:

```bash
cp .env.example .env
```

2. Add your OpenAI key to `.env` or export it in your shell:

```bash
# Linux / macOS
export OPENAI_API_KEY=sk-your-key-here

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-key-here"
```

3. (Optional) Set user-level EduCode home — defaults to `~/.educode/`:

```bash
export EDUCODE_HOME=~/.educode
```

## Quickstart (use in any project)

```bash
# 1. Go to your project
cd /path/to/your-project

# 2. One-time setup: create .educode/ and index the codebase
educode init

# 3. Start interactive session (same as `educode chat`)
educode
```

After `init`, you should see a header with repo, model, and index info, then:

```
Ready. Run: educode chat
```

### First-time shortcut

If you skip `init`, the first `educode` or `educode chat` run will auto-initialize the project and index the repository.

## Daily usage

### Interactive chat (recommended)

```bash
cd /path/to/your-project
educode
```

Or explicitly:

```bash
educode chat
```

Inside the REPL:

| Input | Action |
|-------|--------|
| Your question or task | Agent searches codebase, reads files, responds or proposes edits |
| `/status` | Show current `thread_id` and model |
| `/exit` or `/quit` | End session |
| `Ctrl+C` | Pause; prints resume command with `--thread-id` |

Example prompts:

- `Where is user authentication handled?`
- `Add input validation to the login endpoint`
- `Why is tests/test_users.py failing? Run tests and fix the issue.`

### One-shot task

Run a single task and exit:

```bash
educode run "add pagination to the /users endpoint"
```

### Resume a previous session

Sessions are persisted with a `thread_id` (Sqlite checkpointer). Resume with:

```bash
educode chat --thread-id <your-thread-id>
educode run --thread-id <your-thread-id> "continue previous task"
```

## Global CLI options

These apply to all commands:

```bash
educode [OPTIONS] COMMAND [ARGS]...

Options:
  --version          Show version and exit
  -v, --verbose      Enable DEBUG logging
  --model TEXT       Override model (e.g. openai:gpt-4o-mini)
  --repo DIRECTORY   Project root (default: current directory)
```

Examples:

```bash
educode --repo ~/projects/my-api chat
educode --model openai:gpt-4o-mini run "refactor auth middleware"
educode -v chat
```

## Project initialization (`educode init`)

Creates local EduCode state in your repository:

```
your-project/
├── src/
└── .educode/
    ├── config.yaml          # per-project settings
    ├── rag_manifest.json    # indexed file hashes
    ├── sessions.db          # session metadata
    └── tasks/               # per-thread checkpoint DBs
```

`init` also adds `.educode/` to `.gitignore` when possible.

```bash
educode init                  # full init + codebase indexing
educode init --skip-index     # config only, no indexing
```

Indexing walks your repo (skips `node_modules`, `.venv`, `__pycache__`, etc.), chunks source files, embeds them, and stores vectors in local Qdrant.

## Configuration

### Project config (`.educode/config.yaml`)

```bash
educode config show
educode config set model=openai:gpt-4o-mini
educode config set token_budget=250000
educode config set auto_approve=false
```

Common keys:

| Key | Description | Default |
|-----|-------------|---------|
| `model` | LLM model identifier | `openai:gpt-4o` |
| `token_budget` | Project token budget | `500000` |
| `auto_approve` | Skip approval prompts for mutating tools | `false` |
| `active_skill` | Active skill name (optional) | none |
| `strict_api_keys` | Require API keys at startup | `true` |

### User config (`~/.educode/config.yaml`)

User-level settings override defaults and are merged before project config. Use the same keys as project config.

## Human approval (safety)

Before writing files or running terminal commands, EduCode asks for approval unless `auto_approve=true`:

```
Approve changes? [y/n]
```

Use `y` to approve, `n` to reject. For production work, keep `auto_approve=false`.

## How it works (high level)

1. **Index** — `educode init` chunks and embeds your codebase into local Qdrant.
2. **Retrieve** — During chat/run, the agent calls `search_codebase` to find relevant code.
3. **Plan & execute** — A supervisor delegates to planner, coder, reviewer, and runner sub-agents.
4. **Persist** — Conversation state is checkpointed per `thread_id` for multi-turn sessions and resume.

## Troubleshooting

### `OPENAI_API_KEY is required`

Set the key in your environment or `.env`:

```bash
export OPENAI_API_KEY=sk-...
```

Or run init/chat with project config `strict_api_keys=false` (not recommended for production).

### Agent does not know my codebase

Re-index the project:

```bash
educode init
```

Ensure files are not in ignored directories (`node_modules`, `.venv`, etc.).

### Wrong project directory

Pass `--repo` explicitly:

```bash
educode --repo /absolute/path/to/project chat
```

### Verbose logs for debugging

```bash
educode -v chat
```

## Development

```bash
poetry install --with dev
poetry run pytest tests/unit
poetry run ruff check src tests
```

Mock mode (no API calls) for local testing:

```bash
poetry run educode --model mock:loop run "test task"
```

## License

MIT — see [LICENSE](LICENSE).

## Publishing to PyPI (maintainers)

### One-time PyPI setup

1. Create an account at [pypi.org](https://pypi.org/account/register/).
2. Register the project name `educode-agent` on PyPI (first upload claims it).
3. Enable **Trusted Publishing** on PyPI for this GitHub repo (recommended):
   - PyPI project → Publishing → Add GitHub Actions publisher
   - Repository: `3eyedtech-creator/educode-agent`
   - Workflow: `release.yml`
   - Environment name: `pypi`
4. In GitHub repo **Settings → Environments**, create environment `pypi` (used by the release workflow).

### Release a new version

```bash
# 1. Bump version in pyproject.toml and src/educode_agent/__init__.py
poetry version patch   # or minor / major

# 2. Sync __init__.py version manually to match pyproject.toml

# 3. Commit, tag, and push
git add pyproject.toml src/educode_agent/__init__.py
git commit -m "chore(release): bump version to $(poetry version -s)"
git tag "v$(poetry version -s)"
git push origin main --tags
```

Pushing a `v*.*.*` tag triggers `.github/workflows/release.yml`, which runs tests, builds the wheel/sdist, publishes to PyPI, and creates a GitHub Release.

### Verify locally before publishing

```bash
poetry build
pip install dist/educode_agent-*.whl
educode --version
cd /path/to/a/test/project
educode init --mock-index
educode --model mock:loop run "smoke test"
```

### Manual publish (without GitHub Actions)

```bash
poetry build
poetry publish   # requires PYPI_API_TOKEN configured
```

