plain-agent 0.1.0__tar.gz

plain_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ribo Mo
+
+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.

plain_agent-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: plain-agent
+Version: 0.1.0
+Summary: A small agent that calls OpenAI-compatible APIs.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==2.43.0
+Requires-Dist: python-dotenv>=1.2.2
+Dynamic: license-file
+
+# Plain Agent
+
+A small agent that calls OpenAI compatible LLM APIs.
+
+This project starts with a streaming agent loop:
+
+```text
+Interactive terminal
+  -> reads your prompt
+  -> streams assistant text as it arrives
+  -> detects tool calls from the model
+  -> runs workspace tools when requested
+  -> sends tool results back to the model
+  -> repeats until the assistant gives a final answer
+```
+
+## Install
+
+This project uses `uv` to track the Python environment.
+If `uv` is not installed, follow the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a local `.env` file or export environment variables in your shell. See `.env.example` for more examples.
+
+For DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+export LLM_PROVIDER="deepseek"
+export LLM_MODEL="deepseek-v4-flash"
+```
+
+For OpenAI:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LLM_PROVIDER="openai"
+export LLM_MODEL="gpt-5.4-mini"
+```
+
+You can still set `LLM_BASE_URL` when you want to override the provider default, such as pointing at a local OpenAI compatible server like Ollama.
+
+## Run
+
+```bash
+uv run plain-agent
+```

plain_agent-0.1.0/README.md

@@ -0,0 +1,52 @@
+# Plain Agent
+
+A small agent that calls OpenAI compatible LLM APIs.
+
+This project starts with a streaming agent loop:
+
+```text
+Interactive terminal
+  -> reads your prompt
+  -> streams assistant text as it arrives
+  -> detects tool calls from the model
+  -> runs workspace tools when requested
+  -> sends tool results back to the model
+  -> repeats until the assistant gives a final answer
+```
+
+## Install
+
+This project uses `uv` to track the Python environment.
+If `uv` is not installed, follow the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a local `.env` file or export environment variables in your shell. See `.env.example` for more examples.
+
+For DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+export LLM_PROVIDER="deepseek"
+export LLM_MODEL="deepseek-v4-flash"
+```
+
+For OpenAI:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LLM_PROVIDER="openai"
+export LLM_MODEL="gpt-5.4-mini"
+```
+
+You can still set `LLM_BASE_URL` when you want to override the provider default, such as pointing at a local OpenAI compatible server like Ollama.
+
+## Run
+
+```bash
+uv run plain-agent
+```

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

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: plain-agent
+Version: 0.1.0
+Summary: A small agent that calls OpenAI-compatible APIs.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==2.43.0
+Requires-Dist: python-dotenv>=1.2.2
+Dynamic: license-file
+
+# Plain Agent
+
+A small agent that calls OpenAI compatible LLM APIs.
+
+This project starts with a streaming agent loop:
+
+```text
+Interactive terminal
+  -> reads your prompt
+  -> streams assistant text as it arrives
+  -> detects tool calls from the model
+  -> runs workspace tools when requested
+  -> sends tool results back to the model
+  -> repeats until the assistant gives a final answer
+```
+
+## Install
+
+This project uses `uv` to track the Python environment.
+If `uv` is not installed, follow the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a local `.env` file or export environment variables in your shell. See `.env.example` for more examples.
+
+For DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+export LLM_PROVIDER="deepseek"
+export LLM_MODEL="deepseek-v4-flash"
+```
+
+For OpenAI:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LLM_PROVIDER="openai"
+export LLM_MODEL="gpt-5.4-mini"
+```
+
+You can still set `LLM_BASE_URL` when you want to override the provider default, such as pointing at a local OpenAI compatible server like Ollama.
+
+## Run
+
+```bash
+uv run plain-agent
+```

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

@@ -0,0 +1,33 @@
+LICENSE
+README.md
+pyproject.toml
+plain_agent.egg-info/PKG-INFO
+plain_agent.egg-info/SOURCES.txt
+plain_agent.egg-info/dependency_links.txt
+plain_agent.egg-info/entry_points.txt
+plain_agent.egg-info/requires.txt
+plain_agent.egg-info/top_level.txt
+simple_agent/agent_loop.py
+simple_agent/cli.py
+simple_agent/conversation_history.py
+simple_agent/llm_client.py
+simple_agent/message_types.py
+simple_agent/prompt.py
+simple_agent/streaming.py
+simple_agent/terminal_loop.py
+simple_agent/tools/base_tool.py
+simple_agent/tools/command_policy.py
+simple_agent/tools/command_runtime.py
+simple_agent/tools/edit_file.py
+simple_agent/tools/list_files.py
+simple_agent/tools/read_file.py
+simple_agent/tools/run_command.py
+simple_agent/tools/search_text.py
+simple_agent/tools/tools.py
+simple_agent/tools/utils.py
+simple_agent/tools/write_file.py
+simple_agent/tools/permissions/file_permission.py
+tests/test_agent.py
+tests/test_llm_client.py
+tests/test_terminal_loop.py
+tests/test_tools.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+plain-agent = simple_agent.cli:main

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

@@ -0,0 +1,2 @@
+openai==2.43.0
+python-dotenv>=1.2.2

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

@@ -0,0 +1 @@
+simple_agent

plain_agent-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plain-agent"
+version = "0.1.0"
+description = "A small agent that calls OpenAI-compatible APIs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "openai==2.43.0",
+    "python-dotenv>=1.2.2",
+]
+
+[project.scripts]
+plain-agent = "simple_agent.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["simple_agent*"]

plain_agent-0.1.0/setup.cfg

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

plain_agent-0.1.0/simple_agent/agent_loop.py

@@ -0,0 +1,112 @@
+"""Simple tool loop for the educational agent."""
+
+from collections.abc import Iterable
+import json
+from typing import Any, Callable, Generator
+
+from simple_agent.conversation_history import ConversationHistory
+from simple_agent.message_types import ToolCallDict
+from simple_agent.prompt import INITIAL_PROMPT
+from simple_agent.streaming import (
+    ChatCompletionStreamAccumulator,
+    TextDelta,
+    ToolResult,
+)
+from simple_agent.tools.tools import Tools
+from simple_agent.tools.utils import error
+
+
+class SimpleAgent:
+    """A tiny Chat Completions agent loop with workspace tools."""
+
+    def __init__(
+        self,
+        llm_client: Any,
+        model: str,
+        workspace: str = ".",
+        max_turns: int = 5,
+        command_approver: Callable[[str], bool] | None = None,
+    ) -> None:
+        self.llm_client = llm_client
+        self.model = model
+        self.max_turns = max_turns
+        self.command_approver = command_approver
+        self.tools = Tools(workspace)
+        self.conversation_history = ConversationHistory(INITIAL_PROMPT)
+
+    def respond_stream(self, user_input: str) -> Generator[TextDelta | ToolResult, None, None]:
+        self.conversation_history.append_user(user_input)
+
+        for _ in range(self.max_turns):
+            accumulator = ChatCompletionStreamAccumulator()
+            for chunk in self._create_llm_stream():
+                for event in accumulator.add_chunk(chunk):
+                    yield event
+
+            message_dict = accumulator.assistant_message()
+            self.conversation_history.append(message_dict)
+
+            tool_calls = message_dict.get("tool_calls")
+            if not tool_calls:
+                return
+
+            for tool_call_dict in tool_calls:
+                result = self._handle_tool_call(tool_call_dict)
+                self.conversation_history.append_tool(tool_call_dict["id"], result)
+                yield ToolResult(
+                    call_id=tool_call_dict["id"],
+                    name=tool_call_dict["function"]["name"],
+                    result=result,
+                    ok=self._tool_result_ok(result),
+                )
+
+        final_text = "I stopped because the tool loop reached the max turn limit."
+        self.conversation_history.append_assistant(final_text)
+        yield TextDelta(final_text)
+
+    def _create_llm_stream(self) -> Iterable[Any]:
+        return self.llm_client.chat.completions.create(
+            model=self.model,
+            messages=self.conversation_history.to_messages(),
+            tools=self.tools.definitions(),
+            tool_choice="auto",
+            stream=True,
+        )
+
+    def _handle_tool_call(self, tool_call: ToolCallDict) -> str:
+        name = tool_call["function"]["name"]
+        try:
+            arguments = self._parse_tool_arguments(tool_call["function"]["arguments"])
+        except ValueError as exc:
+            return error(str(exc))
+        user_approval = self._approve_run_command(arguments)
+        if name == "run_command" and not user_approval:
+            return error("run_command was not approved")
+        return self.tools.run(name, arguments)
+
+    def _approve_run_command(self, arguments: dict[str, object]) -> bool:
+        command = arguments.get("command")
+        if not isinstance(command, str) or not command.strip():
+            # Empty or invalid commands are blocked by the tool implementation.
+            return True
+        if self.command_approver is None:
+            return False
+        return self.command_approver(command)
+
+    def _tool_result_ok(self, result: str) -> bool:
+        try:
+            parsed = json.loads(result)
+        except json.JSONDecodeError:
+            return False
+        if not isinstance(parsed, dict):
+            return False
+        return parsed.get("ok") is True
+
+    def _parse_tool_arguments(self, raw_arguments: str) -> dict[str, object]:
+        try:
+            arguments = json.loads(raw_arguments or "{}")
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"invalid JSON arguments: {exc}")
+        if not isinstance(arguments, dict):
+            raise ValueError("tool arguments must be a JSON object")
+        return arguments

plain_agent-0.1.0/simple_agent/cli.py

@@ -0,0 +1,43 @@
+import os
+
+from dotenv import load_dotenv
+
+from simple_agent.agent_loop import SimpleAgent
+from simple_agent.llm_client import (
+    DEEPSEEK_BASE_URL,
+    OPENAI_BASE_URL,
+    OpenAICompatibleClient,
+)
+from simple_agent.terminal_loop import approve_run_command, run_interactive_terminal
+
+
+def main() -> None:
+    load_dotenv()
+
+    provider = os.environ.get("LLM_PROVIDER", "deepseek").lower()
+    timeout = float(os.environ.get("LLM_TIMEOUT", "60"))
+
+    if provider == "openai":
+        api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("LLM_API_KEY")
+        default_model = "gpt-5.4-mini"
+        default_base_url = OPENAI_BASE_URL
+    elif provider == "deepseek":
+        api_key = os.environ.get("DEEPSEEK_API_KEY") or os.environ.get("LLM_API_KEY")
+        default_model = "deepseek-v4-flash"
+        default_base_url = DEEPSEEK_BASE_URL
+    else:
+        raise ValueError("LLM_PROVIDER must be 'openai' or 'deepseek'")
+
+    llm_client = OpenAICompatibleClient(
+        api_key=api_key,
+        base_url=os.environ.get("LLM_BASE_URL", default_base_url),
+        timeout=timeout,
+    )
+    model = os.environ.get("LLM_MODEL", default_model)
+    agent = SimpleAgent(
+        llm_client=llm_client,
+        model=model,
+        command_approver=approve_run_command,
+    )
+
+    run_interactive_terminal(agent)

plain_agent-0.1.0/simple_agent/conversation_history.py

@@ -0,0 +1,59 @@
+"""Typed chat messages and conversation history storage."""
+
+from collections.abc import Iterator
+from copy import deepcopy
+from typing import overload
+
+from simple_agent.message_types import AssistantMessageDict, ChatMessage, ToolMessage, UserMessage
+
+
+class ConversationHistory:
+    """Stores chat messages while exposing list-like read access."""
+    _messages: list[ChatMessage]
+
+    def __init__(self, system_prompt: str) -> None:
+        self._messages = [
+            {"role": "system", "content": system_prompt},
+        ]
+
+    def append(self, message: ChatMessage) -> None:
+        self._messages.append(message)
+
+    def append_user(self, content: str) -> None:
+        message: UserMessage = {"role": "user", "content": content}
+        self.append(message)
+
+    def append_assistant(self, content: str) -> None:
+        message: AssistantMessageDict = {"role": "assistant", "content": content}
+        self.append(message)
+
+    def append_tool(self, tool_call_id: str, content: str) -> None:
+        message: ToolMessage = {
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": content,
+        }
+        self.append(message)
+
+    def replace(self, messages: list[ChatMessage]) -> None:
+        self._messages = messages
+
+    def to_messages(self) -> list[ChatMessage]:
+        return deepcopy(self._messages)
+
+    def __iter__(self) -> Iterator[ChatMessage]:
+        return iter(self._messages)
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+    @overload
+    def __getitem__(self, index: int) -> ChatMessage:
+        ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[ChatMessage]:
+        ...
+
+    def __getitem__(self, index: int | slice) -> ChatMessage | list[ChatMessage]:
+        return self._messages[index]

plain_agent-0.1.0/simple_agent/llm_client.py

@@ -0,0 +1,49 @@
+"""OpenAI-compatible LLM clients."""
+
+from openai import OpenAI
+
+
+OPENAI_BASE_URL = "https://api.openai.com/v1"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+
+
+class LLMClientError(ValueError):
+    """Raised when LLM configuration is incomplete."""
+
+
+class OpenAICompatibleClient:
+    """Small wrapper around the official OpenAI SDK client."""
+
+    base_url = OPENAI_BASE_URL
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise LLMClientError("api_key is required to create an LLM client")
+
+        self.api_key = api_key
+        self.base_url = base_url or self.base_url
+        self.timeout = timeout
+        self.client = OpenAI(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+        )
+
+    @property
+    def chat(self):
+        return self.client.chat
+
+
+class OpenAIClient(OpenAICompatibleClient):
+    """OpenAI client."""
+
+
+class DeepSeekClient(OpenAICompatibleClient):
+    """DeepSeek client using its OpenAI-compatible API."""
+
+    base_url = DEEPSEEK_BASE_URL

plain_agent-0.1.0/simple_agent/message_types.py

@@ -0,0 +1,39 @@
+"""TypedDict shapes for OpenAI-compatible chat messages."""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class SystemMessage(TypedDict):
+    role: Literal["system"]
+    content: str
+
+
+class UserMessage(TypedDict):
+    role: Literal["user"]
+    content: str
+
+
+class ToolMessage(TypedDict):
+    role: Literal["tool"]
+    tool_call_id: str
+    content: str
+
+
+class FunctionCallDict(TypedDict):
+    name: str
+    arguments: str
+
+
+class ToolCallDict(TypedDict):
+    id: str
+    type: Literal["function"]
+    function: FunctionCallDict
+
+
+class AssistantMessageDict(TypedDict):
+    role: Literal["assistant"]
+    content: str | None
+    tool_calls: NotRequired[list[ToolCallDict]]
+
+
+ChatMessage = SystemMessage | UserMessage | AssistantMessageDict | ToolMessage

plain_agent-0.1.0/simple_agent/prompt.py

@@ -0,0 +1,5 @@
+INITIAL_PROMPT = """
+You are a helpful educational coding assistant.
+You may inspect and edit the workspace with tools before answering.
+Use tools when file context would make your answer more accurate.
+"""

plain_agent-0.1.0/simple_agent/streaming.py

@@ -0,0 +1,96 @@
+"""Helpers for Chat Completions streaming responses."""
+
+from dataclasses import dataclass
+
+from openai.types.chat.chat_completion_chunk import (
+    ChatCompletionChunk,
+    ChoiceDeltaToolCall,
+)
+
+from simple_agent.message_types import AssistantMessageDict, ToolCallDict
+
+
+@dataclass
+class TextDelta:
+    """A streamed assistant text chunk."""
+
+    content: str
+
+
+@dataclass
+class ToolResult:
+    """A completed tool call event."""
+
+    call_id: str
+    name: str
+    result: str
+    ok: bool
+
+
+def merge_tool_call_delta_into(tool_call: ToolCallDict, tool_call_delta: ChoiceDeltaToolCall) -> None:
+    # Each streamed delta may contain only one fragment of the final tool call.
+    call_id = tool_call_delta.id
+    if call_id:
+        tool_call["id"] = call_id
+
+    call_type = tool_call_delta.type
+    if call_type:
+        tool_call["type"] = call_type
+
+    function_delta = tool_call_delta.function
+    if function_delta is None:
+        return
+
+    name = function_delta.name
+    if name:
+        tool_call["function"]["name"] += name
+
+    arguments = function_delta.arguments
+    if arguments:
+        tool_call["function"]["arguments"] += arguments
+
+
+class ChatCompletionStreamAccumulator:
+    """Build the final assistant message from streamed Chat Completions chunks."""
+
+    def __init__(self) -> None:
+        self.full_text = ""
+        self.tool_calls_by_index: dict[int, ToolCallDict] = {}
+
+    def add_chunk(self, chunk: ChatCompletionChunk) -> list[TextDelta]:
+        # OpenAI can send usage/bookkeeping chunks with choices=[].
+        choices = chunk.choices
+        if not choices:
+            return []
+
+        delta = choices[0].delta
+        events = []
+
+        content = delta.content
+        if content:
+            self.full_text += content
+            events.append(TextDelta(content))
+
+        for tool_call_delta in delta.tool_calls or []:
+            index = tool_call_delta.index
+            if index not in self.tool_calls_by_index:
+                self.tool_calls_by_index[index] = {
+                    "id": "",
+                    "type": "function",
+                    "function": {"name": "", "arguments": ""},
+                }
+
+            tool_call = self.tool_calls_by_index[index]
+            # Later deltas usually add more argument text for this index.
+            merge_tool_call_delta_into(tool_call, tool_call_delta)
+
+        return events
+
+    def assistant_message(self) -> AssistantMessageDict:
+        message_dict: AssistantMessageDict = {"role": "assistant", "content": self.full_text or None}
+        if self.tool_calls_by_index:
+            message_dict["tool_calls"] = [
+                self.tool_calls_by_index[index]
+                for index in sorted(self.tool_calls_by_index)
+            ]
+        return message_dict