paimon 0.1.0__tar.gz

paimon-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: paimon
+Version: 0.1.0
+Summary: A minimal code agent built on litellm + textual
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: litellm>=1.89.4
+Requires-Dist: textual>=8.2.7
+
+# Paimon
+
+A minimal terminal code agent built on **litellm** (LLM access) and **textual** (TUI).
+
+## Features (MVP)
+
+- Streaming agent loop: LLM + tool calls until the task is done
+- Four tools: `read_file`, `write_file`, `edit_file`, `bash`
+- Live streaming output + reasoning display in a Textual UI
+- Confirmation prompt before dangerous actions (`bash`, `write_file`, `edit_file`)
+
+## Setup
+
+Set these environment variables (uses an OpenAI-compatible endpoint via the
+litellm `openai/` prefix):
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `PAIMON_API_KEY`  | API key for the endpoint | `tp-...` |
+| `PAIMON_MODEL`    | litellm model id | `openai/mimo-v2.5-pro` |
+| `PAIMON_API_BASE` | base URL of the endpoint | `https://token-plan-cn.xiaomimimo.com/v1` |
+
+## Run
+
+```bash
+uv run paimon        # or: uv run main.py
+```
+
+## Layout
+
+| File | Role |
+|------|------|
+| `paimon/config.py` | model config |
+| `paimon/tools.py`  | tool schemas + execution |
+| `paimon/agent.py`  | UI-agnostic agent loop (yields typed events) |
+| `paimon/app.py`    | Textual TUI |

paimon-0.1.0/README.md

@@ -0,0 +1,36 @@
+# Paimon
+
+A minimal terminal code agent built on **litellm** (LLM access) and **textual** (TUI).
+
+## Features (MVP)
+
+- Streaming agent loop: LLM + tool calls until the task is done
+- Four tools: `read_file`, `write_file`, `edit_file`, `bash`
+- Live streaming output + reasoning display in a Textual UI
+- Confirmation prompt before dangerous actions (`bash`, `write_file`, `edit_file`)
+
+## Setup
+
+Set these environment variables (uses an OpenAI-compatible endpoint via the
+litellm `openai/` prefix):
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `PAIMON_API_KEY`  | API key for the endpoint | `tp-...` |
+| `PAIMON_MODEL`    | litellm model id | `openai/mimo-v2.5-pro` |
+| `PAIMON_API_BASE` | base URL of the endpoint | `https://token-plan-cn.xiaomimimo.com/v1` |
+
+## Run
+
+```bash
+uv run paimon        # or: uv run main.py
+```
+
+## Layout
+
+| File | Role |
+|------|------|
+| `paimon/config.py` | model config |
+| `paimon/tools.py`  | tool schemas + execution |
+| `paimon/agent.py`  | UI-agnostic agent loop (yields typed events) |
+| `paimon/app.py`    | Textual TUI |

paimon-0.1.0/paimon/__init__.py

@@ -0,0 +1 @@
+"""Paimon, a minimal code agent built on litellm + textual."""

paimon-0.1.0/paimon/agent.py

@@ -0,0 +1,159 @@
+"""The agent loop: stream from the LLM, run tool calls, repeat until done.
+
+``Agent.run`` is UI-agnostic: it yields typed events that a CLI or a TUI can
+render however it likes.
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import AsyncIterator, Awaitable, Callable, Optional
+
+import litellm
+
+from . import config, tools
+
+litellm.telemetry = False
+litellm.suppress_debug_info = True
+
+
+# ---- Events yielded by Agent.run -------------------------------------------
+
+
+@dataclass
+class TextDelta:
+    text: str
+
+
+@dataclass
+class ReasoningDelta:
+    text: str
+
+
+@dataclass
+class ToolStart:
+    id: str
+    name: str
+    args: dict
+
+
+@dataclass
+class ToolEnd:
+    id: str
+    name: str
+    result: str
+    denied: bool = False
+
+
+@dataclass
+class TurnEnd:
+    pass
+
+
+# A confirm callback returns True to allow a dangerous tool, False to deny.
+ConfirmFn = Callable[[str, dict], Awaitable[bool]]
+
+
+def _system_prompt(cwd: Path) -> str:
+    return f"""You are Paimon, a concise coding assistant operating in a terminal.
+
+You help with software engineering tasks by reading and editing files and running
+shell commands. You have these tools: read_file, write_file, edit_file, bash.
+
+Guidelines:
+- Working directory: {cwd}
+- Today's date: {date.today().isoformat()}
+- Prefer reading a file before editing it. For edits, use edit_file with a unique
+  old_string; only use write_file for new files or full rewrites.
+- Use the bash tool for listing, searching (grep/find/ls), git, and running tests.
+- Be direct. When the task is done, briefly state what you did. Don't narrate every step.
+"""
+
+
+class Agent:
+    def __init__(self, cwd: Optional[Path] = None, confirm: Optional[ConfirmFn] = None):
+        self.cwd = Path(cwd or Path.cwd())
+        self.confirm = confirm
+        self.messages: list[dict] = [
+            {"role": "system", "content": _system_prompt(self.cwd)}
+        ]
+
+    async def run(self, user_input: str) -> AsyncIterator[object]:
+        """Run one user turn to completion, yielding events along the way."""
+        self.messages.append({"role": "user", "content": user_input})
+
+        while True:
+            response = await litellm.acompletion(
+                model=config.MODEL,
+                api_base=config.API_BASE,
+                api_key=config.API_KEY,
+                messages=self.messages,
+                tools=tools.TOOLS,
+                stream=True,
+            )
+
+            content = ""
+            # index -> {"id", "name", "args"} accumulated across stream deltas
+            calls: dict[int, dict] = {}
+
+            async for chunk in response:
+                delta = chunk.choices[0].delta
+
+                reasoning = getattr(delta, "reasoning_content", None)
+                if reasoning:
+                    yield ReasoningDelta(reasoning)
+
+                if delta.content:
+                    content += delta.content
+                    yield TextDelta(delta.content)
+
+                for tc in delta.tool_calls or []:
+                    slot = calls.setdefault(tc.index, {"id": "", "name": "", "args": ""})
+                    if tc.id:
+                        slot["id"] = tc.id
+                    if tc.function and tc.function.name:
+                        slot["name"] = tc.function.name
+                    if tc.function and tc.function.arguments:
+                        slot["args"] += tc.function.arguments
+
+            ordered = [calls[i] for i in sorted(calls)]
+
+            assistant_msg: dict = {"role": "assistant", "content": content or None}
+            if ordered:
+                assistant_msg["tool_calls"] = [
+                    {
+                        "id": c["id"],
+                        "type": "function",
+                        "function": {"name": c["name"], "arguments": c["args"]},
+                    }
+                    for c in ordered
+                ]
+            self.messages.append(assistant_msg)
+
+            if not ordered:
+                yield TurnEnd()
+                return
+
+            for c in ordered:
+                try:
+                    args = json.loads(c["args"] or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+                name = c["name"]
+                yield ToolStart(c["id"], name, args)
+
+                denied = False
+                if self.confirm and name in tools.DANGEROUS:
+                    allowed = await self.confirm(name, args)
+                    if not allowed:
+                        denied = True
+                        result = "User denied this operation."
+                if not denied:
+                    result = await tools.execute_tool(name, args, self.cwd)
+
+                yield ToolEnd(c["id"], name, result, denied=denied)
+                self.messages.append(
+                    {"role": "tool", "tool_call_id": c["id"], "content": result}
+                )
+            # loop again so the model can react to tool results

paimon-0.1.0/paimon/app.py

@@ -0,0 +1,171 @@
+"""Textual TUI for the Paimon agent."""
+
+import json
+from pathlib import Path
+
+from rich.text import Text
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.containers import Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Input, Static
+
+from .agent import (
+    Agent,
+    ReasoningDelta,
+    TextDelta,
+    ToolEnd,
+    ToolStart,
+    TurnEnd,
+)
+
+
+class ConfirmScreen(ModalScreen[bool]):
+    """Yes/No confirmation for a dangerous tool call."""
+
+    BINDINGS = [("y", "allow", "Allow"), ("n", "deny", "Deny"), ("escape", "deny", "Deny")]
+
+    def __init__(self, tool_name: str, args: dict) -> None:
+        super().__init__()
+        self.tool_name = tool_name
+        self.args = args
+
+    def compose(self) -> ComposeResult:
+        detail = self.args.get("command") or self.args.get("path") or ""
+        body = Text()
+        body.append("Allow this action?\n\n", style="bold")
+        body.append(f"{self.tool_name}", style="bold yellow")
+        body.append(f"  {detail}", style="dim")
+        with Vertical(id="confirm-box"):
+            yield Static(body)
+            with Vertical(id="confirm-buttons"):
+                yield Button("Allow (y)", variant="success", id="allow")
+                yield Button("Deny (n)", variant="error", id="deny")
+
+    @on(Button.Pressed, "#allow")
+    def action_allow(self) -> None:
+        self.dismiss(True)
+
+    @on(Button.Pressed, "#deny")
+    def action_deny(self) -> None:
+        self.dismiss(False)
+
+
+class PaimonApp(App):
+    CSS = """
+    #log { height: 1fr; padding: 0 1; }
+    #log > Static { margin-bottom: 1; }
+    ConfirmScreen { align: center middle; }
+    #confirm-box { width: 70%; height: auto; padding: 1 2; border: round $warning; background: $surface; }
+    #confirm-buttons { height: auto; margin-top: 1; }
+    #confirm-buttons Button { margin-right: 2; width: auto; }
+    """
+
+    BINDINGS = [("ctrl+c", "quit", "Quit")]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.agent = Agent(cwd=Path.cwd(), confirm=self._confirm)
+
+    def compose(self) -> ComposeResult:
+        yield VerticalScroll(id="log")
+        yield Input(placeholder="Ask Paimon to do something… (Ctrl+C to quit)")
+
+    def on_mount(self) -> None:
+        self.query_one(Input).focus()
+
+    # ---- rendering helpers --------------------------------------------------
+
+    def _add(self, renderable) -> Static:
+        log = self.query_one("#log", VerticalScroll)
+        widget = Static(renderable)
+        log.mount(widget)
+        log.scroll_end(animate=False)
+        return widget
+
+    def _scroll(self) -> None:
+        self.query_one("#log", VerticalScroll).scroll_end(animate=False)
+
+    # ---- confirmation hook (called from the agent loop) --------------------
+
+    async def _confirm(self, tool_name: str, args: dict) -> bool:
+        return await self.push_screen_wait(ConfirmScreen(tool_name, args))
+
+    # ---- input → turn -------------------------------------------------------
+
+    @on(Input.Submitted)
+    def handle_submit(self, event: Input.Submitted) -> None:
+        text = event.value.strip()
+        if not text:
+            return
+        event.input.value = ""
+        header = Text("You\n", style="bold cyan")
+        header.append(text)
+        self._add(header)
+        self.run_turn(text)
+
+    @work(exclusive=True)
+    async def run_turn(self, text: str) -> None:
+        inp = self.query_one(Input)
+        inp.disabled = True
+        inp.placeholder = "Paimon is working…"
+
+        assistant: Static | None = None
+        buffer = ""
+        reasoning: Static | None = None
+        reasoning_buf = ""
+
+        try:
+            async for ev in self.agent.run(text):
+                if isinstance(ev, ReasoningDelta):
+                    reasoning_buf += ev.text
+                    body = Text(reasoning_buf, style="dim italic")
+                    if reasoning is None:
+                        reasoning = self._add(body)
+                    else:
+                        reasoning.update(body)
+                    self._scroll()
+
+                elif isinstance(ev, TextDelta):
+                    buffer += ev.text
+                    body = Text("Paimon\n", style="bold green")
+                    body.append(buffer)
+                    if assistant is None:
+                        assistant = self._add(body)
+                    else:
+                        assistant.update(body)
+                    self._scroll()
+
+                elif isinstance(ev, ToolStart):
+                    detail = ev.args.get("command") or ev.args.get("path") or json.dumps(ev.args)
+                    line = Text("⚙ ", style="yellow")
+                    line.append(ev.name, style="bold yellow")
+                    line.append(f"  {detail}", style="dim")
+                    self._add(line)
+                    # start fresh assistant/reasoning blocks after a tool runs
+                    assistant, buffer = None, ""
+                    reasoning, reasoning_buf = None, ""
+
+                elif isinstance(ev, ToolEnd):
+                    preview = "\n".join(ev.result.splitlines()[:15])
+                    if len(ev.result.splitlines()) > 15:
+                        preview += "\n…"
+                    style = "red" if ev.denied else "dim"
+                    self._add(Text(preview or "(no output)", style=style))
+
+                elif isinstance(ev, TurnEnd):
+                    pass
+        except Exception as exc:  # noqa: BLE001 — show errors instead of crashing the UI
+            self._add(Text(f"Error: {exc}", style="bold red"))
+        finally:
+            inp.disabled = False
+            inp.placeholder = "Ask Paimon to do something… (Ctrl+C to quit)"
+            inp.focus()
+
+
+def main() -> None:
+    PaimonApp().run()
+
+
+if __name__ == "__main__":
+    main()

paimon-0.1.0/paimon/config.py

@@ -0,0 +1,9 @@
+"""Configuration: model settings read from environment variables.
+"""
+
+import os
+
+# litellm uses the "openai/" prefix to talk to any OpenAI-compatible endpoint.
+MODEL = os.environ.get("PAIMON_MODEL")
+API_BASE = os.environ.get("PAIMON_API_BASE")
+API_KEY = os.environ.get("PAIMON_API_KEY")

paimon-0.1.0/paimon/tools.py

@@ -0,0 +1,157 @@
+"""Tool definitions and execution.
+
+Each tool is described with an OpenAI-style JSON schema (sent to the model) and
+implemented by a small Python function. ``execute_tool`` dispatches by name.
+"""
+
+import asyncio
+from pathlib import Path
+
+# Tools whose side effects warrant a user confirmation before running.
+DANGEROUS = {"bash", "write_file", "edit_file"}
+
+MAX_OUTPUT = 30_000  # truncate tool output sent back to the model
+
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read a text file and return its contents with line numbers.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "File path, relative to the working directory or absolute."},
+                    "offset": {"type": "integer", "description": "1-indexed line to start from (optional)."},
+                    "limit": {"type": "integer", "description": "Maximum number of lines to read (optional)."},
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Create or overwrite a file with the given content.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "edit_file",
+            "description": "Replace an exact substring in a file. old_string must appear exactly once.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "old_string": {"type": "string", "description": "Exact text to replace (must be unique in the file)."},
+                    "new_string": {"type": "string", "description": "Replacement text."},
+                },
+                "required": ["path", "old_string", "new_string"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "bash",
+            "description": "Run a shell command in the working directory and return its combined stdout/stderr. Use this for listing, searching (grep/find/ls), git, running tests, etc.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {"type": "string"},
+                },
+                "required": ["command"],
+            },
+        },
+    },
+]
+
+
+def _resolve(path: str, cwd: Path) -> Path:
+    p = Path(path)
+    return p if p.is_absolute() else cwd / p
+
+
+def _read_file(args: dict, cwd: Path) -> str:
+    path = _resolve(args["path"], cwd)
+    if not path.exists():
+        return f"Error: file not found: {path}"
+    lines = path.read_text(errors="replace").splitlines()
+    offset = max(1, int(args.get("offset", 1)))
+    limit = args.get("limit")
+    end = offset - 1 + int(limit) if limit else len(lines)
+    selected = lines[offset - 1 : end]
+    if not selected:
+        return "(file is empty or offset past end of file)"
+    width = len(str(offset + len(selected) - 1))
+    return "\n".join(f"{offset + i:>{width}}  {line}" for i, line in enumerate(selected))
+
+
+def _write_file(args: dict, cwd: Path) -> str:
+    path = _resolve(args["path"], cwd)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(args["content"])
+    n = args["content"].count("\n") + 1
+    return f"Wrote {n} lines to {path}"
+
+
+def _edit_file(args: dict, cwd: Path) -> str:
+    path = _resolve(args["path"], cwd)
+    if not path.exists():
+        return f"Error: file not found: {path}"
+    text = path.read_text()
+    old = args["old_string"]
+    count = text.count(old)
+    if count == 0:
+        return "Error: old_string not found in file."
+    if count > 1:
+        return f"Error: old_string is not unique (found {count} times). Add more context to make it unique."
+    path.write_text(text.replace(old, args["new_string"], 1))
+    return f"Edited {path}"
+
+
+async def _bash(args: dict, cwd: Path) -> str:
+    proc = await asyncio.create_subprocess_shell(
+        args["command"],
+        cwd=str(cwd),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+    )
+    try:
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=120)
+    except asyncio.TimeoutError:
+        proc.kill()
+        return "Error: command timed out after 120s."
+    out = stdout.decode(errors="replace")
+    status = f"(exit code {proc.returncode})"
+    return f"{out}\n{status}" if out.strip() else status
+
+
+async def execute_tool(name: str, args: dict, cwd: Path) -> str:
+    """Dispatch a tool call. Always returns a string for the model."""
+    try:
+        if name == "read_file":
+            return _read_file(args, cwd)
+        if name == "write_file":
+            return _write_file(args, cwd)
+        if name == "edit_file":
+            return _edit_file(args, cwd)
+        if name == "bash":
+            result = await _bash(args, cwd)
+        else:
+            return f"Error: unknown tool {name!r}"
+    except Exception as exc:  # noqa: BLE001 — surface any tool error to the model
+        return f"Error executing {name}: {exc}"
+    if len(result) > MAX_OUTPUT:
+        result = result[:MAX_OUTPUT] + f"\n... (truncated, {len(result) - MAX_OUTPUT} more chars)"
+    return result

paimon-0.1.0/paimon.egg-info/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: paimon
+Version: 0.1.0
+Summary: A minimal code agent built on litellm + textual
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: litellm>=1.89.4
+Requires-Dist: textual>=8.2.7
+
+# Paimon
+
+A minimal terminal code agent built on **litellm** (LLM access) and **textual** (TUI).
+
+## Features (MVP)
+
+- Streaming agent loop: LLM + tool calls until the task is done
+- Four tools: `read_file`, `write_file`, `edit_file`, `bash`
+- Live streaming output + reasoning display in a Textual UI
+- Confirmation prompt before dangerous actions (`bash`, `write_file`, `edit_file`)
+
+## Setup
+
+Set these environment variables (uses an OpenAI-compatible endpoint via the
+litellm `openai/` prefix):
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `PAIMON_API_KEY`  | API key for the endpoint | `tp-...` |
+| `PAIMON_MODEL`    | litellm model id | `openai/mimo-v2.5-pro` |
+| `PAIMON_API_BASE` | base URL of the endpoint | `https://token-plan-cn.xiaomimimo.com/v1` |
+
+## Run
+
+```bash
+uv run paimon        # or: uv run main.py
+```
+
+## Layout
+
+| File | Role |
+|------|------|
+| `paimon/config.py` | model config |
+| `paimon/tools.py`  | tool schemas + execution |
+| `paimon/agent.py`  | UI-agnostic agent loop (yields typed events) |
+| `paimon/app.py`    | Textual TUI |

paimon-0.1.0/paimon.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+paimon/__init__.py
+paimon/agent.py
+paimon/app.py
+paimon/config.py
+paimon/tools.py
+paimon.egg-info/PKG-INFO
+paimon.egg-info/SOURCES.txt
+paimon.egg-info/dependency_links.txt
+paimon.egg-info/entry_points.txt
+paimon.egg-info/requires.txt
+paimon.egg-info/top_level.txt

paimon-0.1.0/paimon.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

paimon-0.1.0/paimon.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paimon = paimon.app:main

paimon-0.1.0/paimon.egg-info/requires.txt

@@ -0,0 +1,2 @@
+litellm>=1.89.4
+textual>=8.2.7

paimon-0.1.0/paimon.egg-info/top_level.txt

@@ -0,0 +1 @@
+paimon

paimon-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "paimon"
+version = "0.1.0"
+description = "A minimal code agent built on litellm + textual"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "litellm>=1.89.4",
+    "textual>=8.2.7",
+]
+
+[project.scripts]
+paimon = "paimon.app:main"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 120

paimon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+