kittycode 0.1.0__py3-none-any.whl

kittycode/__init__.py

@@ -0,0 +1,10 @@
+"""KittyCode - minimal AI coding agent."""
+
+__version__ = "0.1.0"
+
+from kittycode.agent import Agent
+from kittycode.config import Config
+from kittycode.llm import LLM
+from kittycode.tools import ALL_TOOLS
+
+__all__ = ["Agent", "Config", "LLM", "ALL_TOOLS", "__version__"]

kittycode/__main__.py

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

kittycode/agent.py

@@ -0,0 +1,125 @@
+"""Core agent loop.
+
+This is the heart of KittyCode.
+
+    user message -> LLM (with tools) -> tool calls? -> execute -> loop
+                                      -> text reply? -> return to user
+
+It keeps looping until the LLM responds with plain text, which means it is
+done working and ready to report back.
+"""
+
+import concurrent.futures
+
+from .context import ContextManager
+from .llm import LLM
+from .prompt import system_prompt
+from .skills import load_skills
+from .tools import ALL_TOOLS, get_tool
+from .tools.agent import AgentTool
+from .tools.base import Tool
+
+
+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.skills = []
+        self._system = ""
+        self.refresh_skills(force_reload=True)
+
+        for tool in self.tools:
+            if isinstance(tool, AgentTool):
+                tool._parent_agent = self
+
+    def _full_messages(self) -> list[dict]:
+        self.refresh_skills()
+        return [{"role": "system", "content": self._system}] + self.messages
+
+    def _tool_schemas(self) -> list[dict]:
+        return [tool.schema() for tool 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):
+            response = self.llm.chat(
+                messages=self._full_messages(),
+                tools=self._tool_schemas(),
+                on_token=on_token,
+            )
+
+            if not response.tool_calls:
+                self.messages.append(response.message)
+                return response.content
+
+            self.messages.append(response.message)
+
+            if len(response.tool_calls) == 1:
+                tool_call = response.tool_calls[0]
+                if on_tool:
+                    on_tool(tool_call.name, tool_call.arguments)
+                result = self._exec_tool(tool_call)
+                self.messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tool_call.id,
+                        "content": result,
+                    }
+                )
+            else:
+                results = self._exec_tools_parallel(response.tool_calls, on_tool)
+                for tool_call, result in zip(response.tool_calls, results):
+                    self.messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": result,
+                        }
+                    )
+
+            self.context.maybe_compress(self.messages, self.llm)
+
+        return "(reached maximum tool-call rounds)"
+
+    def _exec_tool(self, tool_call) -> str:
+        """Execute a single tool call and return the result string."""
+        tool = get_tool(tool_call.name)
+        if tool is None:
+            return f"Error: unknown tool '{tool_call.name}'"
+        try:
+            return tool.execute(**tool_call.arguments)
+        except TypeError as exc:
+            return f"Error: bad arguments for {tool_call.name}: {exc}"
+        except Exception as exc:
+            return f"Error executing {tool_call.name}: {exc}"
+
+    def _exec_tools_parallel(self, tool_calls, on_tool=None) -> list[str]:
+        """Run multiple tool calls concurrently using threads."""
+        for tool_call in tool_calls:
+            if on_tool:
+                on_tool(tool_call.name, tool_call.arguments)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+            futures = [pool.submit(self._exec_tool, tool_call) for tool_call in tool_calls]
+            return [future.result() for future in futures]
+
+    def reset(self):
+        """Clear conversation history."""
+        self.messages.clear()
+
+    def refresh_skills(self, force_reload: bool = False):
+        """Refresh cached skill metadata and rebuild the system prompt."""
+        self.skills = load_skills(force_reload=force_reload)
+        self._system = system_prompt(self.tools, self.skills)

kittycode/cli.py

@@ -0,0 +1,367 @@
+"""Interactive CLI for KittyCode."""
+
+import argparse
+import os
+import sys
+
+from prompt_toolkit import prompt as pt_prompt
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.history import FileHistory
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from . import __version__
+from .agent import Agent
+from .config import CONFIG_PATH, Config
+from .llm import LLM
+from .session import list_sessions, load_session, save_session
+
+console = Console()
+
+_BUILTIN_COMMANDS = {
+    "/help": "Show this help",
+    "/reset": "Clear conversation history",
+    "/skills": "Show loaded local skills",
+    "/model": "Switch model mid-conversation",
+    "/tokens": "Show token usage",
+    "/compact": "Compress conversation context",
+    "/save": "Save session to disk",
+    "/sessions": "List saved sessions",
+    "/quit": "Exit KittyCode",
+}
+
+
+class SlashCommandCompleter(Completer):
+    def __init__(self, command_provider):
+        self.command_provider = command_provider
+
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor
+        if not text.startswith("/"):
+            return
+
+        typed = text.casefold()
+
+        for command in sorted(self.command_provider()):
+            if command.casefold().startswith(typed):
+                yield Completion(
+                    command,
+                    start_position=-len(text),
+                    display=command,
+                    display_meta=_BUILTIN_COMMANDS.get(command, "Use this skill"),
+                )
+
+
+def _parse_args():
+    parser = argparse.ArgumentParser(
+        prog="kittycode",
+        description="Minimal AI coding agent. Supports OpenAI-compatible and Anthropic APIs.",
+    )
+    parser.add_argument("-m", "--model", help="Model name (default: value from ~/.kittycode/config.json)")
+    parser.add_argument("--interface", choices=["openai", "anthropic"], help="Interface type (default: value from ~/.kittycode/config.json)")
+    parser.add_argument("--base-url", help="API base URL (default: value from ~/.kittycode/config.json)")
+    parser.add_argument("--api-key", help="API key (default: value from ~/.kittycode/config.json)")
+    parser.add_argument("-p", "--prompt", help="One-shot prompt (non-interactive mode)")
+    parser.add_argument("-r", "--resume", metavar="ID", help="Resume a saved session")
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    return parser.parse_args()
+
+
+def main():
+    args = _parse_args()
+    try:
+        config = Config.from_file()
+    except ValueError as exc:
+        console.print(f"[red bold]Invalid config file:[/] {CONFIG_PATH}")
+        console.print(str(exc))
+        sys.exit(1)
+
+    if args.model:
+        config.model = args.model
+    if args.interface:
+        config.interface = args.interface
+    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(
+            f"Populate {CONFIG_PATH} with JSON such as:\n"
+            "\n"
+            "{\n"
+            '  "interface": "openai",\n'
+            '  "api_key": "sk-...",\n'
+            '  "model": "gpt-4o",\n'
+            '  "base_url": "https://api.openai.com/v1",\n'
+            '  "max_tokens": 4096,\n'
+            '  "temperature": 0,\n'
+            '  "max_context": 128000\n'
+            "}\n"
+        )
+        sys.exit(1)
+
+    llm = LLM(
+        model=config.model,
+        api_key=config.api_key,
+        interface=config.interface,
+        base_url=config.base_url,
+        temperature=config.temperature,
+        max_tokens=config.max_tokens,
+    )
+    agent = Agent(llm=llm, max_context_tokens=config.max_context_tokens)
+
+    if args.resume:
+        loaded = load_session(args.resume)
+        if loaded:
+            agent.messages, _loaded_model = loaded
+            console.print(f"[green]Resumed session: {args.resume}[/green]")
+        else:
+            console.print(f"[red]Session '{args.resume}' not found.[/red]")
+            sys.exit(1)
+
+    if args.prompt:
+        _run_once(agent, args.prompt)
+        return
+
+    _repl(agent, config)
+
+
+def _run_once(agent: Agent, prompt: str):
+    streamed: list[str] = []
+
+    def on_token(token):
+        streamed.append(token)
+        print(token, end="", flush=True)
+
+    def on_tool(name, kwargs):
+        console.print(f"\n[dim]> {name}({_brief(kwargs)})[/dim]")
+
+    response = agent.chat(prompt, on_token=on_token, on_tool=on_tool)
+    if streamed:
+        print()
+    else:
+        console.print(Markdown(response))
+
+
+def _repl(agent: Agent, config: Config):
+    console.print(
+        Panel(
+            f"[bold]KittyCode[/bold] v{__version__}\n"
+            f"Model: [cyan]{config.model}[/cyan]  Interface: [cyan]{config.interface}[/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",
+        )
+    )
+
+    history = FileHistory(os.path.expanduser("~/.kittycode_history"))
+    completer = SlashCommandCompleter(lambda: _slash_command_names(agent.skills))
+    pending_skill = None
+
+    while True:
+        try:
+            agent.refresh_skills()
+            user_input = pt_prompt(
+                "You > ",
+                history=history,
+                completer=completer,
+                complete_while_typing=True,
+            ).strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\nBye!")
+            break
+
+        if not user_input:
+            continue
+
+        resolved_command, matches = _resolve_command_prefix(user_input, agent.skills)
+        if resolved_command and resolved_command != user_input:
+            user_input = resolved_command
+        elif user_input.startswith("/") and matches and resolved_command is None and user_input not in matches:
+            console.print("[yellow]Matching commands:[/yellow] " + ", ".join(matches))
+            continue
+
+        if user_input == "/quit":
+            break
+        if user_input == "/help":
+            _show_help()
+            continue
+        if user_input == "/reset":
+            agent.reset()
+            pending_skill = None
+            console.print("[yellow]Conversation reset.[/yellow]")
+            continue
+        if user_input == "/skills":
+            agent.refresh_skills()
+            _show_skills(agent.skills)
+            continue
+        if user_input == "/tokens":
+            prompt_tokens = agent.llm.total_prompt_tokens
+            completion_tokens = agent.llm.total_completion_tokens
+            console.print(
+                f"Tokens used this session: [cyan]{prompt_tokens}[/cyan] prompt + "
+                f"[cyan]{completion_tokens}[/cyan] completion = [bold]{prompt_tokens + completion_tokens}[/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":
+            session_id = save_session(agent.messages, config.model)
+            console.print(f"[green]Session saved: {session_id}[/green]")
+            console.print(f"Resume with: kittycode -r {session_id}")
+            continue
+        if user_input == "/sessions":
+            sessions = list_sessions()
+            if not sessions:
+                console.print("[dim]No saved sessions.[/dim]")
+            else:
+                for session in sessions:
+                    console.print(
+                        f"  [cyan]{session['id']}[/cyan] ({session['model']}, {session['saved_at']}) {session['preview']}"
+                    )
+            continue
+
+        skill_match = _match_skill_command(user_input, agent.skills)
+        if skill_match is not None:
+            skill, task = skill_match
+            if task:
+                user_input = _build_skill_request(skill, task)
+            else:
+                pending_skill = skill
+                console.print(f"[cyan]Selected skill:[/cyan] /{skill.name}")
+                console.print("[dim]Your next non-command message will use this skill.[/dim]")
+                continue
+        elif pending_skill is not None and not user_input.startswith("/"):
+            user_input = _build_skill_request(pending_skill, user_input)
+            pending_skill = None
+
+        streamed: list[str] = []
+
+        def on_token(token):
+            streamed.append(token)
+            print(token, 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()
+            else:
+                console.print(Markdown(response))
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Interrupted.[/yellow]")
+        except Exception as exc:
+            console.print(f"\n[red]Error: {exc}[/red]")
+
+
+def _show_help():
+    console.print(
+        Panel(
+            "[bold]Commands:[/bold]\n"
+            "  /help          Show this help\n"
+            "  /reset         Clear conversation history\n"
+            "  /skills        Show loaded local skills\n"
+            "  /<skill name>  Use a loaded skill\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 KittyCode",
+            title="KittyCode Help",
+            border_style="dim",
+        )
+    )
+
+
+def _show_skills(skills):
+    console.print(Panel(_format_skills(skills), title="KittyCode Skills", border_style="dim"))
+
+
+def _format_skills(skills) -> str:
+    if not skills:
+        return "No skills loaded from ~/.kittycode/skills"
+
+    lines = []
+    for index, skill in enumerate(skills, 1):
+        lines.append(f"{index}. {skill.name}")
+        lines.append(f"   /{skill.name}")
+        lines.append(f"   {skill.description}")
+        lines.append(f"   {skill.path}")
+    return "\n".join(lines)
+
+
+def _slash_command_names(skills) -> list[str]:
+    names = list(_BUILTIN_COMMANDS)
+    for skill in skills:
+        command = _skill_command_name(skill)
+        if command not in names:
+            names.append(command)
+    return names
+
+
+def _skill_command_name(skill) -> str:
+    return f"/{skill.name}"
+
+
+def _resolve_command_prefix(user_input: str, skills) -> tuple[str | None, list[str]]:
+    if not user_input.startswith("/"):
+        return None, []
+
+    typed = user_input.casefold()
+    matches = [command for command in _slash_command_names(skills) if command.casefold().startswith(typed)]
+    if len(matches) == 1:
+        return matches[0], matches
+    return None, matches
+
+
+def _match_skill_command(user_input: str, skills):
+    lowered = user_input.casefold()
+    for skill in sorted(skills, key=lambda item: len(_skill_command_name(item)), reverse=True):
+        command = _skill_command_name(skill)
+        lowered_command = command.casefold()
+        if lowered == lowered_command:
+            return skill, ""
+        if lowered.startswith(lowered_command + " "):
+            return skill, user_input[len(command):].strip()
+    return None
+
+
+def _build_skill_request(skill, task: str) -> str:
+    return (
+        f'Use the local skill "{skill.name}" for this request.\n'
+        f"Skill description: {skill.description}\n"
+        f"Skill path: {skill.path}\n"
+        "Before doing other work, read its SKILL.md and any related files under that path.\n\n"
+        f"Task:\n{task}"
+    )
+
+
+def _brief(kwargs: dict, maxlen: int = 80) -> str:
+    summary = ", ".join(f"{key}={repr(value)[:40]}" for key, value in kwargs.items())
+    return summary[:maxlen] + ("..." if len(summary) > maxlen else "")

kittycode/config.py

@@ -0,0 +1,67 @@
+"""Configuration loaded from ~/.kittycode/config.json."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".kittycode" / "config.json"
+
+
+def _pick(data: dict, *names: str, default=None):
+    for name in names:
+        value = data.get(name)
+        if value not in (None, ""):
+            return value
+    return default
+
+
+@dataclass
+class Config:
+    interface: str = "openai"
+    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_file(cls, config_path: Path | str | None = None) -> "Config":
+        path = Path(config_path).expanduser() if config_path is not None else CONFIG_PATH
+
+        if not path.exists():
+            return cls()
+
+        try:
+            raw = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"invalid JSON in {path}: {exc}") from exc
+
+        if not isinstance(raw, dict):
+            raise ValueError(f"{path} must contain a JSON object")
+
+        interface = str(_pick(raw, "interface", "KITTYCODE_INTERFACE", default="openai")).lower()
+        if interface not in {"openai", "anthropic"}:
+            raise ValueError("interface must be 'openai' or 'anthropic'")
+
+        default_model = "gpt-4o" if interface == "openai" else "claude-3-7-sonnet-latest"
+
+        return cls(
+            interface=interface,
+            model=str(_pick(raw, "model", "KITTYCODE_MODEL", default=default_model)),
+            api_key=str(_pick(raw, "api_key", "KITTYCODE_API_KEY", default="")),
+            base_url=_pick(raw, "base_url", "KITTYCODE_BASE_URL"),
+            max_tokens=int(_pick(raw, "max_tokens", "KITTYCODE_MAX_TOKENS", default=4096)),
+            temperature=float(_pick(raw, "temperature", "KITTYCODE_TEMPERATURE", default=0.0)),
+            max_context_tokens=int(
+                _pick(
+                    raw,
+                    "max_context_tokens",
+                    "max_context",
+                    "KITTYCODE_MAX_CONTEXT",
+                    default=128000,
+                )
+            ),
+        )