Metadata-Version: 2.4
Name: codegenie-agent
Version: 0.1.1
Summary: Code Genie — a terminal coding agent (read, edit, and run your project from the CLI).
Author: Code Genie
License: MIT
Project-URL: Homepage, https://github.com/your-username/codegenie
Project-URL: Repository, https://github.com/your-username/codegenie
Keywords: cli,coding-agent,llm,groq,openrouter,developer-tools
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.28,>=0.27
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: python-dotenv>=1.0
Provides-Extra: web
Requires-Dist: fastapi<0.116,>=0.115; extra == "web"
Requires-Dist: uvicorn[standard]<0.31,>=0.30; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"

# Code Genie — MVP (Runnable, $0-cost-by-default)

This is a **real, working** implementation, not a mockup. It has been tested end-to-end:
upload → scan → diagnose → (optional) sandbox verify, with automated tests proving the
rule engine actually matches and scores correctly.

## What's real here vs. what's still a roadmap item

✅ Working now:
- ZIP upload with safety checks (zip-bomb ratio, path traversal, size/type limits, empty-zip handling)
- Project scanner (package.json, requirements.txt, Dockerfile, README, monorepo detection)
- **Free rule-based diagnosis engine** — 10 starter known-issues, matches log patterns + dependency version ranges, $0 cost, no API key needed
- Optional LLM fallback (only fires when the rule engine finds nothing) — defaults to `none`, supports free-tier Groq/Gemini/OpenRouter if you choose to add a key
- Docker-based sandbox build verification (network-disabled, memory/CPU/time capped, non-root)
- Basic auth header, naive rate limiting, session TTL + cleanup
- A working frontend (plain HTML/JS, no build step)

🚧 Not yet built (be honest about this with users):
- GitHub OAuth / private repo scanning
- Multi-language support beyond Node/Next.js and basic Python
- A production-grade job queue (current version runs analysis synchronously — fine for low volume, will need Celery/Redis before real concurrent load)
- Hardened sandboxing (this uses plain Docker, not Firecracker/gVisor — fine for a trusted beta, not for hostile public traffic at scale)
- Persistent database (sessions are in-memory — restarting the server loses session state; swap in Postgres/Redis before real users)

## Terminal coding agent (NEW)

Code Genie now ships an interactive **terminal agent** (like Codebuff) that works
directly inside your project. It can read files, list directories, write/overwrite
files, and run shell commands via LLM tool-calling — asking for confirmation before
any mutating action.

```bash
cd codegenie-app
python3 -m venv venv && source venv/bin/activate
pip install -e .          # installs Code Genie + the `codegenie` command

# Configure a tool-calling provider (Groq or OpenRouter):
export LLM_PROVIDER=groq
export LLM_API_KEY=your_groq_key_here
export LLM_MODEL=llama-3.1-8b-instant   # optional override

# Run the agent in the current directory (your project):
codegenie
# ...or point it at another project:
codegenie --dir /path/to/project
# (equivalently: python -m codegenie.cli)
```

In-session commands: `/help`, `/wishes`, `/reset`, `/exit`.

### 🧞 The magic of 3 wishes (monetization)

Like a genie, Code Genie grants **3 free wishes** per login user. A wish is
consumed **only on a successful feature build** — i.e. a turn where the agent
actually wrote a file or ran a command you approved. Pure read/answer turns
(reading code, listing files, asking questions) are **free** and never burn a
wish.

- After each build you'll see: `✨ Wish granted! You have N wishes remaining.`
- After the 3rd, further requests are refused with an upgrade prompt:
  `🧞 You've used all 3 free wishes. Upgrade to Code Genie Pro: https://codegenie.dev/pro`
- Check your balance any time with `/wishes`.
- Usage is tracked per OS login user and persisted to `~/.codegenie/wishes.json`,
  so it survives restarts (a real gate, not a per-session reset).
- **Pro tier:** set `CODEGENIE_PRO=1` to unlock unlimited wishes.

> This is a real, enforced gate built for launch. The upgrade URL is a
> placeholder until a payment system is wired up — swap `UPGRADE_URL` in
> `codegenie/wishes.py` when you have a checkout page.

**How it works** (all under the `codegenie/` package)
- `codegenie/tools.py` — the agent's tools (read_file, list_dir, write_file, run_command), sandboxed to the working directory.
- `codegenie/llm_client.py` — `chat_with_tools()` speaks OpenAI-compatible function calling (Groq / OpenRouter).
- `codegenie/cli_agent.py` — the agent loop: send messages + tool schemas, execute requested tool calls, feed results back until a final answer.
- `codegenie/cli.py` — the interactive REPL, which prompts you before any file write or shell command.

> Note: the agent loop uses OpenAI-compatible tool calling, so set `LLM_PROVIDER=groq` or `openrouter`. Gemini and `none` are not supported for the agent (they remain available for the web app's diagnosis fallback).

**Production behavior (no surprises)**
- **Rate limits:** free-tier providers (especially Groq) return HTTP 429 under load. The agent automatically retries with exponential backoff (honouring `Retry-After`), then reports a clear message instead of crashing. Tune with `LLM_MAX_RETRIES`.
- **Secrets:** your API key is sent only in the `Authorization` header and is never written to disk or included in any error message.
- **Long sessions:** if the conversation outgrows the model's context window the provider returns a 400; the agent tells you to `/reset`. (A v2 improvement is automatic history trimming.)
- **Confirmation:** every `write_file` and `run_command` prompts for `y/N` before running. There is no auto-approve mode yet — by design, for a safe first release.
- **Sandbox:** file tools are restricted to the working directory (path-traversal attempts are refused). `run_command` runs real shell commands in that directory, so only point the agent at projects you trust.

**Publishing it (single-command install for everyone)**
See [DEPLOY.md](DEPLOY.md) for publishing to PyPI so anyone can run:
```bash
pip install codegenie-agent
codegenie
```

## Quick start (local) — web diagnostic app

```bash
cd codegenie-app
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env   # edit if you want to set an API key or LLM provider

pip install -e ".[web]"   # install the optional web-app dependencies
uvicorn codegenie.main:app --reload --port 8000
```

Open `http://localhost:8000` — the frontend is served at the root.

## Run the real tests

```bash
python test_core.py
```

This proves the rule engine matches known issues correctly and degrades confidence
appropriately when dependency versions don't confirm a log-pattern match — no mocking,
real fixture projects.

## Enabling the LLM fallback (optional, still mostly free)

By default `LLM_PROVIDER=none` — the app runs at $0 forever, just with lower coverage
on novel/project-specific bugs (it'll honestly say "couldn't diagnose confidently" instead
of guessing).

To add free-tier coverage for the long tail:

```bash
# .env
LLM_PROVIDER=groq
LLM_API_KEY=your_groq_key_here
LLM_MODEL=llama-3.1-8b-instant
```

Groq, Gemini Flash, and OpenRouter's free-tier open models all work with the same plug
in `backend/llm_client.py` — swap the provider name and key.

## Enabling sandbox verification (Wish 3)

Requires Docker installed on whatever host runs this (a $5-6/mo VPS like Hetzner/Contabo
is enough to start). No paid sandbox service required. If Docker isn't found, Wish 3
returns a clear "skipped" message instead of crashing — it never blocks Wishes 1 and 2.

⚠️ This uses plain Docker with hardening flags (`--network none`, memory/CPU caps, non-root,
timeout), not microVMs. That's a real, intentional tradeoff for a $0-cost MVP — don't expose
this directly to hostile public internet traffic at scale without upgrading to gVisor or a
dedicated low-privilege host first.

## Growing the known-issues database

`data/known_issues.json` has 10 starter rules. This is genuinely the highest-leverage thing
you can spend time on — every new rule you add is permanent, free diagnostic coverage that
never needs an LLM call. Format:

```json
{
  "id": "KI011",
  "name": "short label",
  "tech": "node | python | docker | any",
  "log_patterns": ["regex1", "regex2"],
  "dependency_check": { "package": "x", "version_range": ">=1.0,<2.0" },  // optional
  "confidence": 85,
  "root_cause": "...",
  "fix_commands": ["..."],
  "prevention_tip": "..."
}
```

## Deploying for real (next steps, in order)

1. Set `CODEGENIE_API_KEY` and put this behind real auth before any public exposure.
2. Move sessions from the in-memory dict in `storage.py` to Redis or Postgres.
3. Move analysis from synchronous request handling to a background job queue (Celery/RQ) once you have concurrent users.
4. Add the malware-scan step mentioned in your original test plan (ClamAV is free and self-hostable) before processing uploaded ZIPs in production.
5. Expand `known_issues.json` based on real beta-user failures — track which rule IDs fire most, and which logs hit "no match," to prioritize what to add next.
