pygent 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

pygent/__init__.py

@@ -10,6 +10,7 @@ from .agent import Agent, run_interactive  # noqa: E402,F401, must come after __
 from .models import Model, OpenAIModel  # noqa: E402,F401
 from .errors import PygentError, APIError  # noqa: E402,F401
 from .tools import register_tool, tool  # noqa: E402,F401
+from .task_manager import TaskManager  # noqa: E402,F401
 
 __all__ = [
     "Agent",
@@ -20,4 +21,5 @@ __all__ = [
     "APIError",
     "register_tool",
     "tool",
+    "TaskManager",
 ]

pygent/agent.py

@@ -20,10 +20,10 @@ DEFAULT_MODEL = os.getenv("PYGENT_MODEL", "gpt-4.1-mini")
 SYSTEM_MSG = (
     "You are Pygent, a sandboxed coding assistant.\n"
     "Respond with JSON when you need to use a tool."
-    "If you need to stop, call the `stop` tool.\n"
+    "If you need to stop or finished you task, call the `stop` tool.\n"
     "You can use the following tools:\n"
     f"{json.dumps(tools.TOOL_SCHEMAS, indent=2)}\n"
-    "You can also use the `continue` tool to continue the conversation.\n"
+    "You can also use the `continue` tool to request user input or continue the conversation.\n"
 )
 
 console = Console()
@@ -44,7 +44,10 @@ class Agent:
             self.history.append({"role": "system", "content": self.system_msg})
 
     def step(self, user_msg: str):
+        """Execute one round of interaction with the model."""
+
         self.history.append({"role": "user", "content": user_msg})
+
         assistant_msg = self.model.chat(
             self.history, self.model_name, tools.TOOL_SCHEMAS
         )
@@ -60,12 +63,36 @@ class Agent:
             console.print(Panel(markdown_response, title="Resposta do Agente", title_align="left", border_style="cyan"))
         return assistant_msg
 
-    def run_until_stop(self, user_msg: str, max_steps: int = 10) -> None:
-        """Run steps automatically until the model calls the ``stop`` tool or
-        the step limit is reached."""
+    def run_until_stop(
+        self,
+        user_msg: str,
+        max_steps: int = 20,
+        step_timeout: float | None = None,
+        max_time: float | None = None,
+    ) -> None:
+        """Run steps until ``stop`` is called or limits are reached."""
+
+        if step_timeout is None:
+            env = os.getenv("PYGENT_STEP_TIMEOUT")
+            step_timeout = float(env) if env else None
+        if max_time is None:
+            env = os.getenv("PYGENT_TASK_TIMEOUT")
+            max_time = float(env) if env else None
+
         msg = user_msg
+        start = time.monotonic()
+        self._timed_out = False
         for _ in range(max_steps):
+            if max_time is not None and time.monotonic() - start > max_time:
+                self.history.append({"role": "system", "content": f"[timeout after {max_time}s]"})
+                self._timed_out = True
+                break
+            step_start = time.monotonic()
             assistant_msg = self.step(msg)
+            if step_timeout is not None and time.monotonic() - step_start > step_timeout:
+                self.history.append({"role": "system", "content": f"[timeout after {step_timeout}s]"})
+                self._timed_out = True
+                break
             calls = assistant_msg.tool_calls or []
             if any(c.function.name in ("stop", "continue") for c in calls):
                 break

pygent/runtime.py

@@ -92,6 +92,24 @@ class Runtime:
         p.write_text(content, encoding="utf-8")
         return f"Wrote {p.relative_to(self.base_dir)}"
 
+    def read_file(self, path: Union[str, Path], binary: bool = False) -> str:
+        """Return the contents of a file relative to the workspace."""
+
+        p = self.base_dir / path
+        if not p.exists():
+            return f"file {p.relative_to(self.base_dir)} not found"
+        data = p.read_bytes()
+        if binary:
+            import base64
+
+            return base64.b64encode(data).decode()
+        try:
+            return data.decode()
+        except UnicodeDecodeError:
+            import base64
+
+            return base64.b64encode(data).decode()
+
     def cleanup(self) -> None:
         if self._use_docker and self.container is not None:
             try:

pygent/task_manager.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+"""Manage background tasks executed by sub-agents."""
+
+import os
+import shutil
+import threading
+import uuid
+from dataclasses import dataclass, field
+from typing import Callable, Dict, TYPE_CHECKING
+
+from .runtime import Runtime
+
+if TYPE_CHECKING:  # pragma: no cover - for type hints only
+    from .agent import Agent
+
+
+@dataclass
+class Task:
+    """Represents a delegated task."""
+
+    id: str
+    agent: "Agent"
+    thread: threading.Thread
+    status: str = field(default="running")
+
+
+class TaskManager:
+    """Launch agents asynchronously and track their progress."""
+
+    def __init__(
+        self,
+        agent_factory: Callable[[], "Agent"] | None = None,
+        max_tasks: int | None = None,
+    ) -> None:
+        from .agent import Agent  # local import to avoid circular dependency
+
+        env_max = os.getenv("PYGENT_MAX_TASKS")
+        self.max_tasks = max_tasks if max_tasks is not None else int(env_max or "3")
+        self.agent_factory = agent_factory or Agent
+        self.tasks: Dict[str, Task] = {}
+        self._lock = threading.Lock()
+
+    def start_task(
+        self,
+        prompt: str,
+        parent_rt: Runtime,
+        files: list[str] | None = None,
+        parent_depth: int = 0,
+        step_timeout: float | None = None,
+        task_timeout: float | None = None,
+    ) -> str:
+        """Create a new agent and run ``prompt`` asynchronously."""
+
+        if parent_depth >= 1:
+            raise RuntimeError("nested delegation is not allowed")
+
+        with self._lock:
+            active = sum(t.status == "running" for t in self.tasks.values())
+            if active >= self.max_tasks:
+                raise RuntimeError(f"max {self.max_tasks} tasks reached")
+
+        if step_timeout is None:
+            env = os.getenv("PYGENT_STEP_TIMEOUT")
+            step_timeout = float(env) if env else 60*5 # default 5 minutes
+        if task_timeout is None:
+            env = os.getenv("PYGENT_TASK_TIMEOUT")
+            task_timeout = float(env) if env else 60*20 # default 20 minutes
+
+        agent = self.agent_factory()
+        setattr(agent.runtime, "task_depth", parent_depth + 1)
+        if files:
+            for fp in files:
+                src = parent_rt.base_dir / fp
+                dest = agent.runtime.base_dir / fp
+                if src.is_dir():
+                    shutil.copytree(src, dest, dirs_exist_ok=True)
+                elif src.exists():
+                    dest.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy(src, dest)
+        task_id = uuid.uuid4().hex[:8]
+        task = Task(id=task_id, agent=agent, thread=None)  # type: ignore[arg-type]
+
+        def run() -> None:
+            try:
+                agent.run_until_stop(
+                    prompt,
+                    step_timeout=step_timeout,
+                    max_time=task_timeout,
+                )
+                if getattr(agent, "_timed_out", False):
+                    task.status = f"timeout after {task_timeout}s"
+                else:
+                    task.status = "finished"
+            except Exception as exc:  # pragma: no cover - error propagation
+                task.status = f"error: {exc}"
+
+        t = threading.Thread(target=run, daemon=True)
+        task.thread = t
+        with self._lock:
+            self.tasks[task_id] = task
+        t.start()
+        return task_id
+
+    def status(self, task_id: str) -> str:
+        with self._lock:
+            task = self.tasks.get(task_id)
+        if not task:
+            return f"Task {task_id} not found"
+        return task.status
+
+    def collect_file(self, rt: Runtime, task_id: str, path: str) -> str:
+        """Copy a file from a task workspace into ``rt``."""
+
+        with self._lock:
+            task = self.tasks.get(task_id)
+        if not task:
+            return f"Task {task_id} not found"
+        src = task.agent.runtime.base_dir / path
+        if not src.exists():
+            return f"file {path} not found"
+        dest = rt.base_dir / path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(src, dest)
+        return f"Retrieved {dest.relative_to(rt.base_dir)}"

pygent/tools.py

@@ -5,6 +5,16 @@ import json
 from typing import Any, Callable, Dict, List
 
 from .runtime import Runtime
+from .task_manager import TaskManager
+
+_task_manager: TaskManager | None = None
+
+
+def _get_manager() -> TaskManager:
+    global _task_manager
+    if _task_manager is None:
+        _task_manager = TaskManager()
+    return _task_manager
 
 
 # ---- registry ----
@@ -82,7 +92,7 @@ def _write_file(rt: Runtime, path: str, content: str) -> str:
 
 @tool(
     name="stop",
-    description="Stop the autonomous loop.",
+    description="Stop the autonomous loop. This is a side-effect free tool that does not return any output. Use when finished some task or when you want to stop the agent.",
     parameters={"type": "object", "properties": {}},
 )
 def _stop(rt: Runtime) -> str:  # pragma: no cover - side-effect free
@@ -91,9 +101,96 @@ def _stop(rt: Runtime) -> str:  # pragma: no cover - side-effect free
 
 @tool(
     name="continue",
-    description="Continue the conversation.",
+    description="Request user answer or input. If in your previous message you asked for user input, you can use this tool to continue the conversation.",
     parameters={"type": "object", "properties": {}},
 )
 def _continue(rt: Runtime) -> str:  # pragma: no cover - side-effect free
     return "Continuing the conversation."
 
+
+
+
+@tool(
+    name="delegate_task",
+    description="Create a background task using a new agent and return its ID.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "prompt": {"type": "string", "description": "Instruction for the sub-agent"},
+            "files": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Files to copy to the sub-agent before starting",
+            },
+            "timeout": {"type": "number", "description": "Max seconds for the task"},
+            "step_timeout": {"type": "number", "description": "Time limit per step"},
+        },
+        "required": ["prompt"],
+    },
+)
+def _delegate_task(
+    rt: Runtime,
+    prompt: str,
+    files: list[str] | None = None,
+    timeout: float | None = None,
+    step_timeout: float | None = None,
+) -> str:
+    if getattr(rt, "task_depth", 0) >= 1:
+        return "error: delegation not allowed in sub-tasks"
+    try:
+        tid = _get_manager().start_task(
+            prompt,
+            parent_rt=rt,
+            files=files,
+            parent_depth=getattr(rt, "task_depth", 0),
+            step_timeout=step_timeout,
+            task_timeout=timeout,
+        )
+    except RuntimeError as exc:
+        return str(exc)
+    return f"started {tid}"
+
+
+@tool(
+    name="task_status",
+    description="Check the status of a delegated task.",
+    parameters={
+        "type": "object",
+        "properties": {"task_id": {"type": "string"}},
+        "required": ["task_id"],
+    },
+)
+def _task_status(rt: Runtime, task_id: str) -> str:
+    return _get_manager().status(task_id)
+
+
+@tool(
+    name="collect_file",
+    description="Retrieve a file from a delegated task into the main workspace.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "task_id": {"type": "string"},
+            "path": {"type": "string"},
+        },
+        "required": ["task_id", "path"],
+    },
+)
+def _collect_file(rt: Runtime, task_id: str, path: str) -> str:
+    return _get_manager().collect_file(rt, task_id, path)
+
+
+@tool(
+    name="download_file",
+    description="Return the contents of a file from the workspace (base64 if binary)",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "binary": {"type": "boolean", "default": False},
+        },
+        "required": ["path"],
+    },
+)
+def _download_file(rt: Runtime, path: str, binary: bool = False) -> str:
+    return rt.read_file(path, binary=binary)

pygent-0.1.14.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: pygent
+Version: 0.1.14
+Summary: Pygent is a minimalist coding assistant that runs commands in a Docker container when available and falls back to local execution. See https://marianochaves.github.io/pygent for documentation and https://github.com/marianochaves/pygent for the source code.
+Author-email: Mariano Chaves <mchaves.software@gmail.com>
+Project-URL: Documentation, https://marianochaves.github.io/pygent
+Project-URL: Repository, https://github.com/marianochaves/pygent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7.0
+Requires-Dist: openai>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Provides-Extra: docker
+Requires-Dist: docker>=7.0.0; extra == "docker"
+Provides-Extra: ui
+Requires-Dist: gradio; extra == "ui"
+Dynamic: license-file
+
+# Pygent
+
+Pygent is a coding assistant that executes each request inside an isolated Docker container whenever possible. If Docker is unavailable (for instance on some Windows setups) the commands are executed locally instead. Full documentation is available in the `docs/` directory and at [marianochaves.github.io/pygent](https://marianochaves.github.io/pygent/).
+
+## Features
+
+* Runs commands in ephemeral containers (default image `python:3.12-slim`).
+* Integrates with OpenAI-compatible models to orchestrate each step.
+* Persists the conversation history during the session.
+* Provides a small Python API for use in other projects.
+* Optional web interface via `pygent-ui`.
+* Register your own tools and customise the system prompt.
+
+## Installation
+
+Installing from source is recommended:
+
+```bash
+pip install -e .
+```
+
+Python ≥ 3.9 is required. The package now bundles the `openai` client for model access.
+To run commands in Docker containers also install `pygent[docker]`.
+
+## Configuration
+
+Behaviour can be adjusted via environment variables (see `docs/configuration.md` for a complete list):
+
+* `OPENAI_API_KEY` &ndash; key used to access the OpenAI API.
+  Set this to your API key or a key from any compatible provider.
+* `OPENAI_BASE_URL` &ndash; base URL for OpenAI-compatible APIs
+  (defaults to ``https://api.openai.com/v1``).
+* `PYGENT_MODEL` &ndash; model name used for requests (default `gpt-4.1-mini`).
+* `PYGENT_IMAGE` &ndash; Docker image to create the container (default `python:3.12-slim`).
+* `PYGENT_USE_DOCKER` &ndash; set to `0` to disable Docker and run locally.
+* `PYGENT_MAX_TASKS` &ndash; maximum number of concurrent delegated tasks (default `3`).
+
+## CLI usage
+
+After installing run:
+
+```bash
+pygent
+```
+
+Use `--docker` to run commands inside a container (requires
+`pygent[docker]`). Use `--no-docker` or set `PYGENT_USE_DOCKER=0`
+to force local execution.
+
+Type messages normally; use `/exit` to end the session. Each command is executed
+in the container and the result shown in the terminal.
+Interactive programs that expect input (e.g. running `python` without a script)
+are not supported and will exit immediately.
+For a minimal web interface run `pygent-ui` instead (requires `pygent[ui]`).
+
+
+## API usage
+
+You can also interact directly with the Python code:
+
+```python
+from pygent import Agent
+
+ag = Agent()
+ag.step("echo 'Hello World'")
+# ... more steps
+ag.runtime.cleanup()
+```
+
+See the [examples](https://github.com/marianochaves/pygent/tree/main/examples) folder for more complete scripts. Models can be swapped by
+passing an object implementing the ``Model`` interface when creating the
+``Agent``. The default uses an OpenAI-compatible API, but custom models are
+easy to plug in.
+
+### Using OpenAI and other providers
+
+Set your OpenAI key:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+To use a different provider, set `OPENAI_BASE_URL` to the provider
+endpoint and keep `OPENAI_API_KEY` pointing to the correct key:
+
+```bash
+export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
+export OPENAI_API_KEY="your-provider-key"
+```
+
+## Development
+
+1. Install the test dependencies:
+
+```bash
+pip install -e .[test]
+```
+
+2. Run the test suite:
+
+```bash
+pytest
+```
+
+Use `mkdocs serve` to build the documentation locally.
+
+## License
+
+This project is released under the MIT license. See the `LICENSE` file for details.
+

pygent-0.1.14.dist-info/RECORD

@@ -0,0 +1,18 @@
+pygent/__init__.py,sha256=8TB-wzDeQV0YANON-q7sUkzlIyAmTN6gyz4R-axmoYU,724
+pygent/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+pygent/agent.py,sha256=5aY5HRlnLNwZzU_JD4bdEd9P9JLK3mtV4NJl7go9igY,4077
+pygent/cli.py,sha256=Hz2FZeNMVhxoT5DjCqphXla3TisGJtPEz921LEcpxrA,527
+pygent/errors.py,sha256=s5FBg_v94coSgMh7cfkP4hVXafViGYgCY8QiT698-c4,155
+pygent/models.py,sha256=j3670gjUtvQRGZ5wqGDcQ7ZJVTdT5WiwL7nWTokeYzg,1141
+pygent/openai_compat.py,sha256=cyWFtXt6sDfOlsZd3FuRxbcZMm3WU-DLPBQpbmcuiW8,2617
+pygent/py.typed,sha256=0Wh72UpGSn4lSGW-u3xMV9kxcBHMdwE15IGUqiJTwqo,52
+pygent/runtime.py,sha256=KckSdTSBIooz181ef8krXbSgqTxIaYDMdCy0ryOi7KQ,4386
+pygent/task_manager.py,sha256=kQ2wwBkhPtpluPzKe9T9Hiv1NoxUA3-sEvuIiPqxq90,4167
+pygent/tools.py,sha256=xHpUpG2QcBEvwTilpw8BDlYWY3KG9mItSt0FoKNkohA,5585
+pygent/ui.py,sha256=xqPAvweghPOBBvoD72HzhN6zlXew_3inb8AN7Ck2zpQ,1328
+pygent-0.1.14.dist-info/licenses/LICENSE,sha256=rIktBU2VR4kHzsWul64cbom2zHIgGqYmABoZwSur6T8,1071
+pygent-0.1.14.dist-info/METADATA,sha256=Et3MB9nI0I9Wb9eWEAmKUrd52rS6H9TluAarCzQsiOk,4278
+pygent-0.1.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pygent-0.1.14.dist-info/entry_points.txt,sha256=b9j216E5UpuMrQWRZrwyEmacNEAYvw1tCKkZqdIVIOc,70
+pygent-0.1.14.dist-info/top_level.txt,sha256=P26IYsb-ThK5IkGP_bRuGJQ0Q_Y8JCcbYqVpvULdxDw,7
+pygent-0.1.14.dist-info/RECORD,,

pygent-0.1.12.dist-info/METADATA

@@ -1,20 +0,0 @@
-Metadata-Version: 2.4
-Name: pygent
-Version: 0.1.12
-Summary: Pygent is a minimalist coding assistant that runs commands in a Docker container when available and falls back to local execution. See https://marianochaves.github.io/pygent for documentation and https://github.com/marianochaves/pygent for the source code.
-Author-email: Mariano Chaves <mchaves.software@gmail.com>
-Project-URL: Documentation, https://marianochaves.github.io/pygent
-Project-URL: Repository, https://github.com/marianochaves/pygent
-Requires-Python: >=3.9
-License-File: LICENSE
-Requires-Dist: rich>=13.7.0
-Requires-Dist: openai>=1.0.0
-Provides-Extra: test
-Requires-Dist: pytest; extra == "test"
-Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Provides-Extra: docker
-Requires-Dist: docker>=7.0.0; extra == "docker"
-Provides-Extra: ui
-Requires-Dist: gradio; extra == "ui"
-Dynamic: license-file

pygent-0.1.12.dist-info/RECORD

@@ -1,17 +0,0 @@
-pygent/__init__.py,sha256=L4IRxHYfzucHUjSMvYHG-1uoTe6XaYJkaHLXuGs4CI8,648
-pygent/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
-pygent/agent.py,sha256=ZyY9dEvB6bnM1ZFLh4XKQJ68v8xpRlP3HM2RRm6Y6Q0,3030
-pygent/cli.py,sha256=Hz2FZeNMVhxoT5DjCqphXla3TisGJtPEz921LEcpxrA,527
-pygent/errors.py,sha256=s5FBg_v94coSgMh7cfkP4hVXafViGYgCY8QiT698-c4,155
-pygent/models.py,sha256=j3670gjUtvQRGZ5wqGDcQ7ZJVTdT5WiwL7nWTokeYzg,1141
-pygent/openai_compat.py,sha256=cyWFtXt6sDfOlsZd3FuRxbcZMm3WU-DLPBQpbmcuiW8,2617
-pygent/py.typed,sha256=0Wh72UpGSn4lSGW-u3xMV9kxcBHMdwE15IGUqiJTwqo,52
-pygent/runtime.py,sha256=xD77DPFUfmbAwsIA5SjlEmj_TimFtN3j-6h53aUVdF0,3821
-pygent/tools.py,sha256=H2oice1Dyl-rw6Rq9hgWxpGSlxDD3ylCpxha8-4dkZQ,2568
-pygent/ui.py,sha256=xqPAvweghPOBBvoD72HzhN6zlXew_3inb8AN7Ck2zpQ,1328
-pygent-0.1.12.dist-info/licenses/LICENSE,sha256=rIktBU2VR4kHzsWul64cbom2zHIgGqYmABoZwSur6T8,1071
-pygent-0.1.12.dist-info/METADATA,sha256=896zkz6xObtzwzVoM77ts8BYMgx-lNQzuUCe8YkBv74,878
-pygent-0.1.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pygent-0.1.12.dist-info/entry_points.txt,sha256=b9j216E5UpuMrQWRZrwyEmacNEAYvw1tCKkZqdIVIOc,70
-pygent-0.1.12.dist-info/top_level.txt,sha256=P26IYsb-ThK5IkGP_bRuGJQ0Q_Y8JCcbYqVpvULdxDw,7
-pygent-0.1.12.dist-info/RECORD,,