comet-code 0.1.0__tar.gz

comet_code-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv python:*)",
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)"
+    ]
+  }
+}

comet_code-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+PROJECT_SPEC.md
+.idea/
+.venv/
+.env
+__pycache__/

comet_code-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

comet_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pritivi Rajkumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

comet_code-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: comet-code
+Version: 0.1.0
+Summary: Agentic CLI coding assistant
+Project-URL: Homepage, https://github.com/pritivi03/comet-code
+Project-URL: Repository, https://github.com/pritivi03/comet-code
+Project-URL: Issues, https://github.com/pritivi03/comet-code/issues
+Author: Pritivi Rajkumar
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,coding-assistant,langgraph,llm,openrouter
+Classifier: Development Status :: 3 - Alpha
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-core>=1.2.28
+Requires-Dist: langchain-openai>=1.1.12
+Requires-Dist: langgraph>=1.1.6
+Requires-Dist: prompt-toolkit>=3.0.47
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# CometCode
+
+An agentic coding assistant for the terminal. Give it a task — it reads your codebase, reasons about what to change, proposes edits, and applies them only after you approve.
+
+Built from scratch on **LangGraph** and **OpenRouter**, with a streaming **Rich** terminal UI.
+
+---
+
+## Demo
+
+```
+mode → implement
+╭────────────────────────────────────────────────────────────╮
+│ add a /clear command that resets conversation history       │
+╰────────────────────────────────────────────────────────────╯
+
+  tool
+    ● Read src/cli/commands.py done
+    └ def handle_command(text, console, state, orchestrator):
+    ● Edit src/cli/commands.py done
+    └ [ok] replaced 1 occurrence(s)
+
+╭──────────────────────────── response ──────────────────────╮
+│ Added `/clear` — it calls `orchestrator.reset_history()`   │
+│ and clears `state.last_tool_history`.                       │
+╰────────────────────────────────────────────────────────────╯
+
+↓ ~3.2k tokens  Cooked for 8s
+```
+
+---
+
+## Architecture
+
+CometCode is structured as a **LangGraph state machine** where each node receives the full `AgentState` and returns state updates. The graph has two nodes — `call_llm` and `execute_tools` — connected by conditional edges that route based on the model's response type.
+
+```
+START → call_llm ──→ execute_tools ──┐
+            ↑                        │
+            └────────────────────────┘
+            (loops until final answer or budget exhausted)
+```
+
+**Key design decisions:**
+
+- **AgentState as the single source of truth** — conversation history, token budgets, tool-call counters, evidence notes, and attempt metadata all live in one typed dict that flows through the graph. Nodes are pure: they receive state, return a patch.
+
+- **Dual invocation paths** — models that support native function calling stream through `_invoke_native`; models that don't fall back to `_invoke_json_fallback` with a structured Pydantic output schema. The rest of the system is unaware of the difference.
+
+- **Explicit budget enforcement** — the graph tracks `tool_calls_used`, `consecutive_no_signal`, and `repeat_call_streak`. Hitting any limit triggers a soft-stop: the model is forced into a final answer using whatever evidence it collected, rather than erroring.
+
+- **Human-in-the-loop approval** — mutating tools (`write_file`, `replace_text`) are gated behind a `request_approval` callback. After approval and execution, the loop returns to the LLM so it sees the updated file state before proposing the next edit — preventing duplicate proposals.
+
+- **Mode-scoped prompting** — `explain`, `debug`, `refactor`, `implement`, and `plan` modes each carry different system instructions and tool permissions. Read-only modes (`explain`, `plan`) never receive mutating tools in their schema.
+
+---
+
+## Features
+
+- **Five task modes** — `explain`, `debug`, `refactor`, `implement`, `plan`
+- **Multi-model support** — route to any OpenRouter model; native tool calling used when available, JSON schema fallback otherwise
+- **Streaming terminal UI** — live spinner with real-time token count and elapsed timer; tool history with colored unified diffs for proposed changes
+- **Persistent conversation history** — context carries across turns within a session; mode switches are surfaced to the model explicitly
+- **Slash command interface** — `/mode`, `/model`, `/tools`, `/clear`, `/help` with tab-completion
+- **Self-limiting agent** — budget caps on tool calls, no-signal streaks, and repeated identical calls; graceful degradation to best-effort answers
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Agent orchestration | [LangGraph](https://github.com/langchain-ai/langgraph) |
+| LLM routing | [OpenRouter](https://openrouter.ai) via LangChain `ChatOpenAI` |
+| Terminal UI | [Rich](https://github.com/Textualize/rich) + [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) |
+| Schema validation | [Pydantic v2](https://docs.pydantic.dev) |
+| Python | 3.12+ |
+
+---
+
+## Getting Started
+
+```bash
+git clone https://github.com/pritivi03/comet-code
+cd comet-code
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+# Add your OpenRouter API key
+echo "OPENROUTER_API_KEY=your_key_here" > .env
+
+python -m main
+```
+
+### Slash commands
+
+| Command | Description |
+|---|---|
+| `/mode <name>` | Switch task mode (`explain`, `debug`, `refactor`, `implement`, `plan`) |
+| `/model <name>` | Switch model (by alias, slug, or label) |
+| `/tools` | Show last run tool history |
+| `/clear` | Reset conversation history |
+| `/help` | List all commands |
+
+---
+
+## Project Layout
+
+```
+src/
+  cli/          # Terminal UI, input handling, rendering, slash commands
+  core/         # LangGraph graph, nodes, orchestrator, state schema
+  llm/          # OpenRouter client, model catalog, prompt builder
+  schemas/      # Pydantic models (events, tasks, state, tools)
+  tools/        # Tool implementations (read_file, search_text, replace_text, …)
+```
+
+---
+
+## License
+
+MIT

comet_code-0.1.0/README.md

@@ -0,0 +1,122 @@
+# CometCode
+
+An agentic coding assistant for the terminal. Give it a task — it reads your codebase, reasons about what to change, proposes edits, and applies them only after you approve.
+
+Built from scratch on **LangGraph** and **OpenRouter**, with a streaming **Rich** terminal UI.
+
+---
+
+## Demo
+
+```
+mode → implement
+╭────────────────────────────────────────────────────────────╮
+│ add a /clear command that resets conversation history       │
+╰────────────────────────────────────────────────────────────╯
+
+  tool
+    ● Read src/cli/commands.py done
+    └ def handle_command(text, console, state, orchestrator):
+    ● Edit src/cli/commands.py done
+    └ [ok] replaced 1 occurrence(s)
+
+╭──────────────────────────── response ──────────────────────╮
+│ Added `/clear` — it calls `orchestrator.reset_history()`   │
+│ and clears `state.last_tool_history`.                       │
+╰────────────────────────────────────────────────────────────╯
+
+↓ ~3.2k tokens  Cooked for 8s
+```
+
+---
+
+## Architecture
+
+CometCode is structured as a **LangGraph state machine** where each node receives the full `AgentState` and returns state updates. The graph has two nodes — `call_llm` and `execute_tools` — connected by conditional edges that route based on the model's response type.
+
+```
+START → call_llm ──→ execute_tools ──┐
+            ↑                        │
+            └────────────────────────┘
+            (loops until final answer or budget exhausted)
+```
+
+**Key design decisions:**
+
+- **AgentState as the single source of truth** — conversation history, token budgets, tool-call counters, evidence notes, and attempt metadata all live in one typed dict that flows through the graph. Nodes are pure: they receive state, return a patch.
+
+- **Dual invocation paths** — models that support native function calling stream through `_invoke_native`; models that don't fall back to `_invoke_json_fallback` with a structured Pydantic output schema. The rest of the system is unaware of the difference.
+
+- **Explicit budget enforcement** — the graph tracks `tool_calls_used`, `consecutive_no_signal`, and `repeat_call_streak`. Hitting any limit triggers a soft-stop: the model is forced into a final answer using whatever evidence it collected, rather than erroring.
+
+- **Human-in-the-loop approval** — mutating tools (`write_file`, `replace_text`) are gated behind a `request_approval` callback. After approval and execution, the loop returns to the LLM so it sees the updated file state before proposing the next edit — preventing duplicate proposals.
+
+- **Mode-scoped prompting** — `explain`, `debug`, `refactor`, `implement`, and `plan` modes each carry different system instructions and tool permissions. Read-only modes (`explain`, `plan`) never receive mutating tools in their schema.
+
+---
+
+## Features
+
+- **Five task modes** — `explain`, `debug`, `refactor`, `implement`, `plan`
+- **Multi-model support** — route to any OpenRouter model; native tool calling used when available, JSON schema fallback otherwise
+- **Streaming terminal UI** — live spinner with real-time token count and elapsed timer; tool history with colored unified diffs for proposed changes
+- **Persistent conversation history** — context carries across turns within a session; mode switches are surfaced to the model explicitly
+- **Slash command interface** — `/mode`, `/model`, `/tools`, `/clear`, `/help` with tab-completion
+- **Self-limiting agent** — budget caps on tool calls, no-signal streaks, and repeated identical calls; graceful degradation to best-effort answers
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Agent orchestration | [LangGraph](https://github.com/langchain-ai/langgraph) |
+| LLM routing | [OpenRouter](https://openrouter.ai) via LangChain `ChatOpenAI` |
+| Terminal UI | [Rich](https://github.com/Textualize/rich) + [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) |
+| Schema validation | [Pydantic v2](https://docs.pydantic.dev) |
+| Python | 3.12+ |
+
+---
+
+## Getting Started
+
+```bash
+git clone https://github.com/pritivi03/comet-code
+cd comet-code
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+# Add your OpenRouter API key
+echo "OPENROUTER_API_KEY=your_key_here" > .env
+
+python -m main
+```
+
+### Slash commands
+
+| Command | Description |
+|---|---|
+| `/mode <name>` | Switch task mode (`explain`, `debug`, `refactor`, `implement`, `plan`) |
+| `/model <name>` | Switch model (by alias, slug, or label) |
+| `/tools` | Show last run tool history |
+| `/clear` | Reset conversation history |
+| `/help` | List all commands |
+
+---
+
+## Project Layout
+
+```
+src/
+  cli/          # Terminal UI, input handling, rendering, slash commands
+  core/         # LangGraph graph, nodes, orchestrator, state schema
+  llm/          # OpenRouter client, model catalog, prompt builder
+  schemas/      # Pydantic models (events, tasks, state, tools)
+  tools/        # Tool implementations (read_file, search_text, replace_text, …)
+```
+
+---
+
+## License
+
+MIT

comet_code-0.1.0/main.py

@@ -0,0 +1,91 @@
+"""Comet entrypoint.
+
+Installed as the `comet` console script via pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import warnings
+warnings.filterwarnings("ignore", ".*Pydantic V1.*")
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from cli.ui import run_shell
+from config import config_file_path, is_valid_key, mask_key, resolve_api_key, save_key
+
+app = typer.Typer(
+    name="comet",
+    help="Comet — agentic CLI coding assistant.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+
+
+def _prompt_for_key(console: Console) -> str | None:
+    """Ask the user for an OpenRouter API key on first run.
+
+    Returns the key if provided (and optionally saved), or None if skipped.
+    """
+    console.print(
+        Panel(
+            Text.from_markup(
+                "No OpenRouter API key found.\n\n"
+                "Get one at [bold]https://openrouter.ai/keys[/bold]\n\n"
+                "You can also skip this and set it later:\n"
+                "  • Set [bold]OPENROUTER_API_KEY[/bold] in your environment\n"
+                f"  • Or run [bold]/key set <key>[/bold] inside the shell (saves to {config_file_path()})"
+            ),
+            title="[bold bright_cyan]API Key Setup[/bold bright_cyan]",
+            border_style="bright_blue",
+            padding=(1, 2),
+        )
+    )
+
+    while True:
+        raw = console.input(
+            "[bold bright_cyan]Enter API key[/bold bright_cyan] [dim](or press Enter to skip)[/dim]: "
+        ).strip()
+
+        if not raw:
+            console.print("[dim]Skipping — you can set it later with /key set <key>[/dim]")
+            return None
+
+        if not is_valid_key(raw):
+            console.print("[red]Invalid key:[/red] OpenRouter keys must start with [bold]sk-or-[/bold]")
+            continue
+
+        save_prompt = console.input(
+            f"[dim]Save to {config_file_path()}?[/dim] [bold bright_cyan][Y/n][/bold bright_cyan] "
+        ).strip().lower()
+
+        if save_prompt in {"", "y", "yes"}:
+            save_key(raw)
+            console.print(
+                f"[bright_cyan]Saved[/bright_cyan] [dim]{mask_key(raw)}  ({config_file_path()})[/dim]"
+            )
+        else:
+            console.print("[dim]Key not saved — will only be used for this session[/dim]")
+
+        return raw
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Launch the interactive Comet shell when no subcommand is given."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    console = Console()
+    api_key = resolve_api_key()
+
+    if api_key is None:
+        api_key = _prompt_for_key(console) or ""
+
+    run_shell(api_key=api_key)
+
+
+if __name__ == "__main__":
+    app()

comet_code-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "comet-code"
+version = "0.1.0"
+description = "Agentic CLI coding assistant"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+  { name = "Pritivi Rajkumar" },
+]
+license = { text = "MIT" }
+keywords = ["cli", "coding-assistant", "llm", "agent", "openrouter", "langgraph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "prompt-toolkit>=3.0.47",
+    "pydantic>=2.7.0",
+    "httpx>=0.27.0",
+    "langgraph>=1.1.6",
+    "langchain-core>=1.2.28",
+    "langchain-openai>=1.1.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/pritivi03/comet-code"
+Repository = "https://github.com/pritivi03/comet-code"
+Issues = "https://github.com/pritivi03/comet-code/issues"
+
+[project.scripts]
+comet = "main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/cli",
+    "src/core",
+    "src/llm",
+    "src/schemas",
+    "src/tools",
+]
+force-include = { "main.py" = "main.py", "src/config.py" = "config.py" }

comet_code-0.1.0/src/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entrypoints."""