corecoder 0.2.0__py3-none-any.whl

corecoder/__init__.py

@@ -0,0 +1,10 @@
+"""CoreCoder - Minimal AI coding agent inspired by Claude Code's architecture."""
+
+__version__ = "0.1.0"
+
+from corecoder.agent import Agent
+from corecoder.llm import LLM
+from corecoder.config import Config
+from corecoder.tools import ALL_TOOLS
+
+__all__ = ["Agent", "LLM", "Config", "ALL_TOOLS", "__version__"]

corecoder/__main__.py

@@ -0,0 +1,3 @@
+from corecoder.cli import main
+
+main()

corecoder/agent.py

@@ -0,0 +1,122 @@
+"""Core agent loop.
+
+This is the heart of CoreCoder.  The pattern is simple:
+
+    user message -> LLM (with tools) -> tool calls? -> execute -> loop
+                                      -> text reply? -> return to user
+
+It keeps looping until the LLM responds with plain text (no tool calls),
+which means it's done working and ready to report back.
+"""
+
+import concurrent.futures
+from .llm import LLM
+from .tools import ALL_TOOLS, get_tool
+from .tools.base import Tool
+from .tools.agent import AgentTool
+from .prompt import system_prompt
+from .context import ContextManager
+
+
+class Agent:
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[Tool] | None = None,
+        max_context_tokens: int = 128_000,
+        max_rounds: int = 50,
+    ):
+        self.llm = llm
+        self.tools = tools if tools is not None else ALL_TOOLS
+        self.messages: list[dict] = []
+        self.context = ContextManager(max_tokens=max_context_tokens)
+        self.max_rounds = max_rounds
+        self._system = system_prompt(self.tools)
+
+        # wire up sub-agent capability
+        for t in self.tools:
+            if isinstance(t, AgentTool):
+                t._parent_agent = self
+
+    def _full_messages(self) -> list[dict]:
+        return [{"role": "system", "content": self._system}] + self.messages
+
+    def _tool_schemas(self) -> list[dict]:
+        return [t.schema() for t in self.tools]
+
+    def chat(self, user_input: str, on_token=None, on_tool=None) -> str:
+        """Process one user message. May involve multiple LLM/tool rounds."""
+        self.messages.append({"role": "user", "content": user_input})
+        self.context.maybe_compress(self.messages, self.llm)
+
+        for _ in range(self.max_rounds):
+            resp = self.llm.chat(
+                messages=self._full_messages(),
+                tools=self._tool_schemas(),
+                on_token=on_token,
+            )
+
+            # no tool calls -> LLM is done, return text
+            if not resp.tool_calls:
+                self.messages.append(resp.message)
+                return resp.content
+
+            # tool calls -> execute (parallel when multiple, like Claude Code's
+            # StreamingToolExecutor which runs independent tools concurrently)
+            self.messages.append(resp.message)
+
+            if len(resp.tool_calls) == 1:
+                tc = resp.tool_calls[0]
+                if on_tool:
+                    on_tool(tc.name, tc.arguments)
+                result = self._exec_tool(tc)
+                self.messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": result,
+                })
+            else:
+                # parallel execution for multiple tool calls
+                results = self._exec_tools_parallel(resp.tool_calls, on_tool)
+                for tc, result in zip(resp.tool_calls, results):
+                    self.messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": result,
+                    })
+
+            # compress if tool outputs are big
+            self.context.maybe_compress(self.messages, self.llm)
+
+        return "(reached maximum tool-call rounds)"
+
+    def _exec_tool(self, tc) -> str:
+        """Execute a single tool call, returning the result string."""
+        tool = get_tool(tc.name)
+        if tool is None:
+            return f"Error: unknown tool '{tc.name}'"
+        try:
+            return tool.execute(**tc.arguments)
+        except TypeError as e:
+            return f"Error: bad arguments for {tc.name}: {e}"
+        except Exception as e:
+            return f"Error executing {tc.name}: {e}"
+
+    def _exec_tools_parallel(self, tool_calls, on_tool=None) -> list[str]:
+        """Run multiple tool calls concurrently using threads.
+
+        This is inspired by Claude Code's StreamingToolExecutor which starts
+        executing tools while the model is still generating.  We simplify to:
+        when the model returns N tool calls at once, run them in parallel.
+        """
+        for tc in tool_calls:
+            if on_tool:
+                on_tool(tc.name, tc.arguments)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+            futures = [pool.submit(self._exec_tool, tc) for tc in tool_calls]
+            return [f.result() for f in futures]
+
+    def reset(self):
+        """Clear conversation history."""
+        self.messages.clear()

corecoder/cli.py

@@ -0,0 +1,218 @@
+"""Interactive REPL - the user-facing terminal interface."""
+
+import sys
+import os
+import argparse
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from prompt_toolkit import prompt as pt_prompt
+from prompt_toolkit.history import FileHistory
+
+from .agent import Agent
+from .llm import LLM
+from .config import Config
+from .session import save_session, load_session, list_sessions
+from . import __version__
+
+console = Console()
+
+
+def _parse_args():
+    p = argparse.ArgumentParser(
+        prog="corecoder",
+        description="Minimal AI coding agent. Works with any OpenAI-compatible LLM.",
+    )
+    p.add_argument("-m", "--model", help="Model name (default: $CORECODER_MODEL or gpt-4o)")
+    p.add_argument("--base-url", help="API base URL (default: $OPENAI_BASE_URL)")
+    p.add_argument("--api-key", help="API key (default: $OPENAI_API_KEY)")
+    p.add_argument("-p", "--prompt", help="One-shot prompt (non-interactive mode)")
+    p.add_argument("-r", "--resume", metavar="ID", help="Resume a saved session")
+    p.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    return p.parse_args()
+
+
+def main():
+    args = _parse_args()
+    config = Config.from_env()
+
+    # CLI args override env vars
+    if args.model:
+        config.model = args.model
+    if args.base_url:
+        config.base_url = args.base_url
+    if args.api_key:
+        config.api_key = args.api_key
+
+    if not config.api_key:
+        console.print("[red bold]No API key found.[/]")
+        console.print(
+            "Set one of: OPENAI_API_KEY, DEEPSEEK_API_KEY, or CORECODER_API_KEY\n"
+            "\nExamples:\n"
+            "  # OpenAI\n"
+            "  export OPENAI_API_KEY=sk-...\n"
+            "\n"
+            "  # DeepSeek\n"
+            "  export OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com\n"
+            "\n"
+            "  # Ollama (local)\n"
+            "  export OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder\n"
+        )
+        sys.exit(1)
+
+    llm = LLM(
+        model=config.model,
+        api_key=config.api_key,
+        base_url=config.base_url,
+        temperature=config.temperature,
+        max_tokens=config.max_tokens,
+    )
+    agent = Agent(llm=llm, max_context_tokens=config.max_context_tokens)
+
+    # resume saved session
+    if args.resume:
+        loaded = load_session(args.resume)
+        if loaded:
+            agent.messages, loaded_model = loaded
+            # restore the model from the saved session unless overridden by CLI
+            if not args.model:
+                agent.llm.model = loaded_model
+                config.model = loaded_model
+            console.print(f"[green]Resumed session: {args.resume} (model: {agent.llm.model})[/green]")
+        else:
+            console.print(f"[red]Session '{args.resume}' not found.[/red]")
+            sys.exit(1)
+
+    # one-shot mode
+    if args.prompt:
+        _run_once(agent, args.prompt)
+        return
+
+    # interactive REPL
+    _repl(agent, config)
+
+
+def _run_once(agent: Agent, prompt: str):
+    """Non-interactive: run one prompt and exit."""
+    def on_token(tok):
+        print(tok, end="", flush=True)
+
+    def on_tool(name, kwargs):
+        console.print(f"\n[dim]> {name}({_brief(kwargs)})[/dim]")
+
+    agent.chat(prompt, on_token=on_token, on_tool=on_tool)
+    print()
+
+
+def _repl(agent: Agent, config: Config):
+    """Interactive read-eval-print loop."""
+    console.print(Panel(
+        f"[bold]CoreCoder[/bold] v{__version__}\n"
+        f"Model: [cyan]{config.model}[/cyan]"
+        + (f"  Base: [dim]{config.base_url}[/dim]" if config.base_url else "")
+        + "\nType [bold]/help[/bold] for commands, [bold]Ctrl+C[/bold] to cancel, [bold]quit[/bold] to exit.",
+        border_style="blue",
+    ))
+
+    hist_path = os.path.expanduser("~/.corecoder_history")
+    history = FileHistory(hist_path)
+
+    while True:
+        try:
+            user_input = pt_prompt("You > ", history=history).strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\nBye!")
+            break
+
+        if not user_input:
+            continue
+
+        # built-in commands
+        if user_input.lower() in ("quit", "exit", "/quit", "/exit"):
+            break
+        if user_input == "/help":
+            _show_help()
+            continue
+        if user_input == "/reset":
+            agent.reset()
+            console.print("[yellow]Conversation reset.[/yellow]")
+            continue
+        if user_input == "/tokens":
+            p = agent.llm.total_prompt_tokens
+            c = agent.llm.total_completion_tokens
+            console.print(f"Tokens used this session: [cyan]{p}[/cyan] prompt + [cyan]{c}[/cyan] completion = [bold]{p+c}[/bold] total")
+            continue
+        if user_input.startswith("/model "):
+            new_model = user_input[7:].strip()
+            if new_model:
+                agent.llm.model = new_model
+                config.model = new_model
+                console.print(f"Switched to [cyan]{new_model}[/cyan]")
+            continue
+        if user_input == "/compact":
+            from .context import estimate_tokens
+            before = estimate_tokens(agent.messages)
+            compressed = agent.context.maybe_compress(agent.messages, agent.llm)
+            after = estimate_tokens(agent.messages)
+            if compressed:
+                console.print(f"[green]Compressed: {before} → {after} tokens ({len(agent.messages)} messages)[/green]")
+            else:
+                console.print(f"[dim]Nothing to compress ({before} tokens, {len(agent.messages)} messages)[/dim]")
+            continue
+        if user_input == "/save":
+            sid = save_session(agent.messages, config.model)
+            console.print(f"[green]Session saved: {sid}[/green]")
+            console.print(f"Resume with: corecoder -r {sid}")
+            continue
+        if user_input == "/sessions":
+            sessions = list_sessions()
+            if not sessions:
+                console.print("[dim]No saved sessions.[/dim]")
+            else:
+                for s in sessions:
+                    console.print(f"  [cyan]{s['id']}[/cyan] ({s['model']}, {s['saved_at']}) {s['preview']}")
+            continue
+
+        # call the agent
+        streamed: list[str] = []
+
+        def on_token(tok):
+            streamed.append(tok)
+            print(tok, end="", flush=True)
+
+        def on_tool(name, kwargs):
+            console.print(f"\n[dim]> {name}({_brief(kwargs)})[/dim]")
+
+        try:
+            response = agent.chat(user_input, on_token=on_token, on_tool=on_tool)
+            if streamed:
+                print()  # newline after streamed tokens
+            else:
+                # response wasn't streamed (came after tool calls)
+                console.print(Markdown(response))
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Interrupted.[/yellow]")
+        except Exception as e:
+            console.print(f"\n[red]Error: {e}[/red]")
+
+
+def _show_help():
+    console.print(Panel(
+        "[bold]Commands:[/bold]\n"
+        "  /help          Show this help\n"
+        "  /reset         Clear conversation history\n"
+        "  /model <name>  Switch model mid-conversation\n"
+        "  /tokens        Show token usage\n"
+        "  /compact       Compress conversation context\n"
+        "  /save          Save session to disk\n"
+        "  /sessions      List saved sessions\n"
+        "  quit           Exit CoreCoder",
+        title="CoreCoder Help",
+        border_style="dim",
+    ))
+
+
+def _brief(kwargs: dict, maxlen: int = 80) -> str:
+    s = ", ".join(f"{k}={repr(v)[:40]}" for k, v in kwargs.items())
+    return s[:maxlen] + ("..." if len(s) > maxlen else "")

corecoder/config.py

@@ -0,0 +1,55 @@
+"""Configuration - env vars and defaults."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _load_dotenv():
+    """Load .env from cwd, walking up to home dir. No-op if python-dotenv missing."""
+    try:
+        from dotenv import load_dotenv
+        # search cwd first, then parent dirs up to ~
+        env_path = Path(".env")
+        if not env_path.exists():
+            cur = Path.cwd()
+            home = Path.home()
+            while cur != home and cur != cur.parent:
+                candidate = cur / ".env"
+                if candidate.exists():
+                    env_path = candidate
+                    break
+                cur = cur.parent
+        load_dotenv(env_path, override=False)
+    except ImportError:
+        pass  # python-dotenv not installed, silently skip
+
+
+@dataclass
+class Config:
+    model: str = "gpt-4o"
+    api_key: str = ""
+    base_url: str | None = None
+    max_tokens: int = 4096
+    temperature: float = 0.0
+    max_context_tokens: int = 128_000
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        # load .env if present (won't override existing env vars)
+        _load_dotenv()
+        # pick up common env vars automatically
+        api_key = (
+            os.getenv("CORECODER_API_KEY")
+            or os.getenv("OPENAI_API_KEY")
+            or os.getenv("DEEPSEEK_API_KEY")
+            or ""
+        )
+        return cls(
+            model=os.getenv("CORECODER_MODEL", "gpt-4o"),
+            api_key=api_key,
+            base_url=os.getenv("OPENAI_BASE_URL") or os.getenv("CORECODER_BASE_URL"),
+            max_tokens=int(os.getenv("CORECODER_MAX_TOKENS", "4096")),
+            temperature=float(os.getenv("CORECODER_TEMPERATURE", "0")),
+            max_context_tokens=int(os.getenv("CORECODER_MAX_CONTEXT", "128000")),
+        )

corecoder/context.py

@@ -0,0 +1,196 @@
+"""Multi-layer context compression.
+
+Claude Code uses a 4-layer strategy:
+  1. HISTORY_SNIP   - trim old tool outputs to a one-line summary
+  2. Microcompact   - LLM-powered summary of old turns (cached)
+  3. CONTEXT_COLLAPSE - aggressive compression when nearing hard limit
+  4. Autocompact    - periodic background compaction
+
+CoreCoder implements the same idea in 3 layers:
+  Layer 1 (tool_snip)   - replace verbose tool results with truncated versions
+  Layer 2 (summarize)   - LLM-powered summary of old conversation
+  Layer 3 (hard_collapse) - last resort: drop everything except summary + recent
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .llm import LLM
+
+
+def _approx_tokens(text: str) -> int:
+    """Rough token count. ~3.5 chars/token for mixed en/zh content."""
+    return len(text) // 3
+
+
+def estimate_tokens(messages: list[dict]) -> int:
+    total = 0
+    for m in messages:
+        if m.get("content"):
+            total += _approx_tokens(m["content"])
+        if m.get("tool_calls"):
+            total += _approx_tokens(str(m["tool_calls"]))
+    return total
+
+
+class ContextManager:
+    def __init__(self, max_tokens: int = 128_000):
+        self.max_tokens = max_tokens
+        # layer thresholds (fraction of max_tokens)
+        self._snip_at = int(max_tokens * 0.50)    # 50% -> snip tool outputs
+        self._summarize_at = int(max_tokens * 0.70)  # 70% -> LLM summarize
+        self._collapse_at = int(max_tokens * 0.90)   # 90% -> hard collapse
+
+    def maybe_compress(self, messages: list[dict], llm: LLM | None = None) -> bool:
+        """Apply compression layers as needed. Returns True if any compression happened."""
+        current = estimate_tokens(messages)
+        compressed = False
+
+        # Layer 1: snip verbose tool outputs
+        if current > self._snip_at:
+            if self._snip_tool_outputs(messages):
+                compressed = True
+                current = estimate_tokens(messages)
+
+        # Layer 2: LLM-powered summarization of old turns
+        if current > self._summarize_at and len(messages) > 10:
+            if self._summarize_old(messages, llm, keep_recent=8):
+                compressed = True
+                current = estimate_tokens(messages)
+
+        # Layer 3: hard collapse - last resort
+        if current > self._collapse_at and len(messages) > 4:
+            self._hard_collapse(messages, llm)
+            compressed = True
+
+        return compressed
+
+    @staticmethod
+    def _snip_tool_outputs(messages: list[dict]) -> bool:
+        """Layer 1: Truncate tool results over 1500 chars to their first/last lines.
+
+        This mirrors Claude Code's HISTORY_SNIP which replaces old tool outputs
+        with a one-line summary to reclaim context space.
+        """
+        changed = False
+        for m in messages:
+            if m.get("role") != "tool":
+                continue
+            content = m.get("content", "")
+            if len(content) <= 1500:
+                continue
+            lines = content.splitlines()
+            if len(lines) <= 6:
+                continue
+            # keep first 3 + last 3 lines
+            snipped = (
+                "\n".join(lines[:3])
+                + f"\n... ({len(lines)} lines, snipped to save context) ...\n"
+                + "\n".join(lines[-3:])
+            )
+            m["content"] = snipped
+            changed = True
+        return changed
+
+    def _summarize_old(self, messages: list[dict], llm: LLM | None,
+                       keep_recent: int = 8) -> bool:
+        """Layer 2: Summarize old conversation, keep recent messages intact."""
+        if len(messages) <= keep_recent:
+            return False
+
+        old = messages[:-keep_recent]
+        tail = messages[-keep_recent:]
+
+        summary = self._get_summary(old, llm)
+
+        messages.clear()
+        messages.append({
+            "role": "user",
+            "content": f"[Context compressed - conversation summary]\n{summary}",
+        })
+        messages.append({
+            "role": "assistant",
+            "content": "Got it, I have the context from our earlier conversation.",
+        })
+        messages.extend(tail)
+        return True
+
+    def _hard_collapse(self, messages: list[dict], llm: LLM | None):
+        """Layer 3: Emergency compression. Keep only last 4 messages + summary."""
+        tail = messages[-4:] if len(messages) > 4 else messages[-2:]
+        summary = self._get_summary(messages[:-len(tail)], llm)
+
+        messages.clear()
+        messages.append({
+            "role": "user",
+            "content": f"[Hard context reset]\n{summary}",
+        })
+        messages.append({
+            "role": "assistant",
+            "content": "Context restored. Continuing from where we left off.",
+        })
+        messages.extend(tail)
+
+    def _get_summary(self, messages: list[dict], llm: LLM | None) -> str:
+        """Generate summary via LLM or fallback to extraction."""
+        flat = self._flatten(messages)
+
+        if llm:
+            try:
+                resp = llm.chat(
+                    messages=[
+                        {
+                            "role": "system",
+                            "content": (
+                                "Compress this conversation into a brief summary. "
+                                "Preserve: file paths edited, key decisions made, "
+                                "errors encountered, current task state. "
+                                "Drop: verbose command output, code listings, "
+                                "redundant back-and-forth."
+                            ),
+                        },
+                        {"role": "user", "content": flat[:15000]},
+                    ],
+                )
+                return resp.content
+            except Exception:
+                pass
+
+        # fallback: extract key lines
+        return self._extract_key_info(messages)
+
+    @staticmethod
+    def _flatten(messages: list[dict]) -> str:
+        parts = []
+        for m in messages:
+            role = m.get("role", "?")
+            text = m.get("content", "") or ""
+            if text:
+                parts.append(f"[{role}] {text[:400]}")
+        return "\n".join(parts)
+
+    @staticmethod
+    def _extract_key_info(messages: list[dict]) -> str:
+        """Fallback: extract file paths, errors, and decisions without LLM."""
+        import re
+        files_seen = set()
+        errors = []
+        decisions = []
+
+        for m in messages:
+            text = m.get("content", "") or ""
+            # extract file paths
+            for match in re.finditer(r'[\w./\-]+\.\w{1,5}', text):
+                files_seen.add(match.group())
+            # extract error lines
+            for line in text.splitlines():
+                if 'error' in line.lower() or 'Error' in line:
+                    errors.append(line.strip()[:150])
+
+        parts = []
+        if files_seen:
+            parts.append(f"Files touched: {', '.join(sorted(files_seen)[:20])}")
+        if errors:
+            parts.append(f"Errors seen: {'; '.join(errors[:5])}")
+        return "\n".join(parts) or "(no extractable context)"