agentic-loop 0.3.0__py3-none-any.whl

agentic_loop/tools/registry.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from agentic_loop.llm.openai_compat import parse_tool_arguments
+
+ToolHandler = Callable[[dict[str, Any]], Awaitable[str] | str]
+
+
+@dataclass
+class RegisteredTool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    handler: ToolHandler
+    requires_bash: bool = False
+
+
+class ToolRegistry:
+    def __init__(self, *, cwd: Path, allow_bash: bool = False) -> None:
+        self.cwd = cwd.resolve()
+        self.allow_bash = allow_bash
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def register(
+        self,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        handler: ToolHandler,
+        *,
+        requires_bash: bool = False,
+    ) -> None:
+        self._tools[name] = RegisteredTool(
+            name=name,
+            description=description,
+            parameters=parameters,
+            handler=handler,
+            requires_bash=requires_bash,
+        )
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                },
+            }
+            for tool in self._tools.values()
+        ]
+
+    async def execute(self, name: str, arguments: str) -> str:
+        if name not in self._tools:
+            return f"Error: unknown tool '{name}'"
+
+        tool = self._tools[name]
+        if tool.requires_bash and not self.allow_bash:
+            return "Error: bash tool disabled. Re-run with --allow-bash."
+
+        try:
+            args = parse_tool_arguments(arguments)
+        except ValueError as exc:
+            return f"Error: {exc}"
+
+        try:
+            result = tool.handler(args)
+            if asyncio.iscoroutine(result):
+                result = await result
+            return str(result)
+        except Exception as exc:  # noqa: BLE001 - tool errors become observations
+            return f"Error: {exc}"
+
+    def list_names(self) -> list[str]:
+        return sorted(self._tools.keys())
+
+
+def _resolve_path(cwd: Path, raw: str) -> Path:
+    path = Path(raw)
+    if not path.is_absolute():
+        path = cwd / path
+    resolved = path.resolve()
+    if cwd not in resolved.parents and resolved != cwd:
+        raise ValueError(f"Path escapes workspace: {raw}")
+    return resolved
+
+
+async def read_file_handler(cwd: Path, args: dict[str, Any]) -> str:
+    path = _resolve_path(cwd, str(args["path"]))
+    if not path.is_file():
+        return f"Error: file not found: {path}"
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="utf-8", errors="replace")
+
+
+async def write_file_handler(cwd: Path, args: dict[str, Any]) -> str:
+    path = _resolve_path(cwd, str(args["path"]))
+    content = str(args.get("content", ""))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return f"Wrote {len(content)} bytes to {path.relative_to(cwd)}"
+
+
+async def grep_handler(cwd: Path, args: dict[str, Any]) -> str:
+    pattern = str(args["pattern"])
+    root = _resolve_path(cwd, str(args.get("path", ".")))
+    if root.is_file():
+        targets = [root]
+    else:
+        targets = [p for p in root.rglob("*") if p.is_file()]
+
+    regex = re.compile(pattern)
+    matches: list[str] = []
+    for file_path in targets:
+        if ".venv" in file_path.parts or ".git" in file_path.parts:
+            continue
+        try:
+            text = file_path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for idx, line in enumerate(text.splitlines(), start=1):
+            if regex.search(line):
+                rel = file_path.relative_to(cwd)
+                matches.append(f"{rel}:{idx}:{line[:200]}")
+                if len(matches) >= 100:
+                    return "\n".join(matches) + "\n...(truncated at 100 matches)"
+
+    if not matches:
+        return "No matches found."
+    return "\n".join(matches)
+
+
+async def bash_handler(cwd: Path, args: dict[str, Any]) -> str:
+    command = str(args["command"])
+    timeout = float(args.get("timeout", 60))
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        cwd=str(cwd),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+    except asyncio.TimeoutError:
+        proc.kill()
+        return f"Error: timeout after {timeout}s"
+
+    parts: list[str] = []
+    if stdout:
+        parts.append(stdout.decode("utf-8", errors="replace"))
+    if stderr:
+        parts.append(stderr.decode("utf-8", errors="replace"))
+    if proc.returncode not in (0, None):
+        parts.append(f"exit code: {proc.returncode}")
+    return "\n".join(parts).strip() or "(no output)"
+
+
+def build_default_registry(*, cwd: Path, allow_bash: bool = False) -> ToolRegistry:
+    registry = ToolRegistry(cwd=cwd, allow_bash=allow_bash)
+
+    registry.register(
+        "read_file",
+        "Read a UTF-8 text file relative to the workspace.",
+        {
+            "type": "object",
+            "properties": {"path": {"type": "string", "description": "File path"}},
+            "required": ["path"],
+        },
+        lambda args: read_file_handler(cwd, args),
+    )
+    registry.register(
+        "write_file",
+        "Write content to a file relative to the workspace.",
+        {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+        lambda args: write_file_handler(cwd, args),
+    )
+    registry.register(
+        "grep",
+        "Search file contents under a path using a regex pattern.",
+        {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "path": {"type": "string", "description": "File or directory", "default": "."},
+            },
+            "required": ["pattern"],
+        },
+        lambda args: grep_handler(cwd, args),
+    )
+    registry.register(
+        "bash",
+        "Run a shell command in the workspace directory.",
+        {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "timeout": {"type": "number", "default": 60},
+            },
+            "required": ["command"],
+        },
+        lambda args: bash_handler(cwd, args),
+        requires_bash=True,
+    )
+    return registry

agentic_loop/worktree/manager.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import subprocess
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class WorktreeInfo:
+    path: Path
+    branch: str
+
+
+class WorktreeManager:
+    def __init__(self, repo_root: Path) -> None:
+        self.repo_root = repo_root.resolve()
+        self.base_dir = self.repo_root / ".agentic-loop" / "worktrees"
+
+    def create(self, *, prefix: str = "agent") -> WorktreeInfo:
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        branch = f"{prefix}/{uuid.uuid4().hex[:8]}"
+        path = self.base_dir / branch.replace("/", "-")
+        subprocess.run(
+            ["git", "worktree", "add", "-b", branch, str(path)],
+            cwd=str(self.repo_root),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return WorktreeInfo(path=path, branch=branch)
+
+    def remove(self, info: WorktreeInfo) -> None:
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", str(info.path)],
+            cwd=str(self.repo_root),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        subprocess.run(
+            ["git", "branch", "-D", info.branch],
+            cwd=str(self.repo_root),
+            check=False,
+            capture_output=True,
+            text=True,
+        )

agentic_loop-0.3.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: agentic-loop
+Version: 0.3.0
+Summary: Lightweight Loop Engineering orchestrator for self-hosted agent loops
+Author: Agentic-Loop contributors
+License: MIT
+Project-URL: Homepage, https://github.com/WenSongWang/Agentic-Loop
+Project-URL: Repository, https://github.com/WenSongWang/Agentic-Loop
+Project-URL: Documentation, https://github.com/WenSongWang/Agentic-Loop#readme
+Project-URL: Issues, https://github.com/WenSongWang/Agentic-Loop/issues
+Keywords: agent,llm,loop-engineering,orchestrator,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.40.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: webhook
+Requires-Dist: fastapi>=0.115.0; extra == "webhook"
+Requires-Dist: uvicorn>=0.32.0; extra == "webhook"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: pytest>=8.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.24; extra == "all"
+Requires-Dist: build>=1.0; extra == "all"
+Requires-Dist: twine>=5.0; extra == "all"
+Requires-Dist: fastapi>=0.115.0; extra == "all"
+Requires-Dist: uvicorn>=0.32.0; extra == "all"
+Requires-Dist: mcp>=1.0.0; extra == "all"
+Dynamic: license-file
+
+# Agentic Loop
+
+Lightweight **Loop Engineering** orchestrator — self-hosted agent loops with tools, state memory, sub-agents, `/goal`, and scheduled automations.
+
+Fork-friendly (MIT). See [docs/architecture.md](docs/architecture.md) and [docs/extending.md](docs/extending.md).
+
+## Install from PyPI
+
+```powershell
+pip install agentic-loop
+pip install "agentic-loop[webhook]"   # FastAPI server example
+pip install "agentic-loop[mcp]"       # MCP connector
+```
+
+See [docs/publishing.md](docs/publishing.md) for maintainers.
+
+## Quick Start (development)
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+copy .env.example .env   # set OPENAI_API_KEY + DMXAPI base URL
+```
+
+```powershell
+agentic-loop run "Summarize README" --dry-run
+agentic-loop loop --every 5m "Triage issues" --once --dry-run
+agentic-loop goal "tests pass" "Fix tests" --dry-run
+agentic-loop state show
+```
+
+Example project: [examples/daily-triage](examples/daily-triage/)
+
+## Commands
+
+| Command | Purpose |
+| :--- | :--- |
+| `run` | Single agent loop with tools |
+| `loop --every 5m` | Automation (Addy: Automations) |
+| `goal "condition" "prompt"` | Run until evaluator confirms goal |
+| `state show` | Persistent memory (state.json + triage) |
+
+Common flags: `--cwd`, `--max-turns`, `--skill`, `--agent`, `--allow-bash`, `--dry-run`, `--no-stream`, `--json`
+
+## Loop Engineering modules
+
+| Module | CLI / path |
+| :--- | :--- |
+| Memory | `state show` → `.agentic-loop/state.json` |
+| Skills | `--skill name` → `skills/*/SKILL.md` |
+| Sub-agents | `--agent name` → `.agentic-loop/agents/*.toml` |
+| Goal | `goal` + `EVALUATOR_MODEL` |
+| Automations | `loop --every` |
+
+Run logs: `.agentic-loop/runs/<run_id>.jsonl`
+
+## Development
+
+```powershell
+pytest tests/ -q
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agentic_loop-0.3.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+agentic_loop/__init__.py,sha256=dSeVtMzZR0uX75LZL3-B-miBiRX_5dcTN3a5RtJAZdQ,964
+agentic_loop/abort.py,sha256=zxFz2dYJrjQzXvmo73FoD4Jp3vLOjExR_eTVG6ia820,398
+agentic_loop/api.py,sha256=T33a5ikWw_GWmPnCzu8wairKKzL6SgEt4x40_riNRz8,3605
+agentic_loop/cli.py,sha256=GOJ5Nig2reAuQLaNsrwxF4WhW4x-Blvksl6TqBEk7RA,10559
+agentic_loop/config.py,sha256=bXsuAketlUt_-OghM0ICOk5vSxT_VwCSQoNhY1CBTOs,2267
+agentic_loop/loop.py,sha256=GCvkIVrztBl5j32k-wL85HOwkUy9-h1hSfjWI09t5XM,7092
+agentic_loop/state.py,sha256=v-htIs-EoyPMu4HTL9nz0rnJpnOdXU_v3d5mR1fmIm4,772
+agentic_loop/terminal.py,sha256=0301DEY8mbbX5ZEnPjKuQY_D5fumjKP_wQV2LwDL0VM,1557
+agentic_loop/connectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/connectors/base.py,sha256=th65FFfjnbmhP77gO4WK184SELoEjFNwvabZsHa3WlA,1112
+agentic_loop/connectors/mcp.py,sha256=MN6yvLfCpXIsZiGjUrVjrnc0m0mnQh9_6umx0GZYY7A,3545
+agentic_loop/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/llm/client.py,sha256=GHclE7KWcyty2aOuP-cg4Y2Reayp3RENOnNvD-k1z8E,895
+agentic_loop/llm/openai_compat.py,sha256=i_c7PtgAdoXP_E1t20bomGm094ENRXLmKySW7vgMwVA,5412
+agentic_loop/llm/retry.py,sha256=AJkmWRXxxL2eD1I_9wl2-vG4_YiD-UPHvzfZH3ABb9A,1126
+agentic_loop/observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/observability/journal.py,sha256=veKe7hKl1INU_dvhPH9rriqoRmFlGKNRz7PNk1h1f04,1618
+agentic_loop/orchestration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/orchestration/automations.py,sha256=T_-oEC5zEy7IXV80VdOVMom1MmC42J9rbfi1d71SSkI,1429
+agentic_loop/orchestration/goal.py,sha256=ckwegI60b2JkHdeO-KB6fmFG346j47QnwwUQflbsTVI,4138
+agentic_loop/orchestration/memory.py,sha256=7dFy3hRow7EXBcSheqxVVu0MivV0dz3uJXPWQ5oxuL4,5081
+agentic_loop/orchestration/orchestrator.py,sha256=kcQ94b420gCA210AmJ-d7BRwUlt-MFAaxGxUNYFXX38,4572
+agentic_loop/orchestration/subagents.py,sha256=wKKIQmOUpIpnaaASfRCu2So6s-_1XkxnFNNpxlUc2AE,2024
+agentic_loop/skills/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/skills/loader.py,sha256=8L3CEIljA9uPVQTbx9zyJlHMSWZa8HPpvfQXuIPas_8,1663
+agentic_loop/tools/__init__.py,sha256=4EG_o6B0mr9ApTD1tYMSPHbzwpOQUOsKkn2r-y4AfCk,131
+agentic_loop/tools/builtin.py,sha256=tsC9Exx5aaRia45X4TW-AoQG3w9vre7PJdAniegGaNU,101
+agentic_loop/tools/mcp_bridge.py,sha256=GC8uxTL_anzRzxpVvmqlySilU9kGXIom9nOmZJ5Nwf8,1099
+agentic_loop/tools/registry.py,sha256=t6kVU0t4rY8YQaFqfZcNXScPz7N8-6FkfVG5i6XKHsA,6882
+agentic_loop/worktree/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_loop/worktree/manager.py,sha256=jDGGtHQ0Vpd30Bnu4RFLuErwQRcTUD_nCONMWa4OWiw,1354
+agentic_loop-0.3.0.dist-info/licenses/LICENSE,sha256=vbQY5BQgLg7CC7m5DKYj5lnEsGINwaLwAIO1Ur0Nojo,1082
+agentic_loop-0.3.0.dist-info/METADATA,sha256=UP2-SazzuaWb9yZfTrOOyLQm7c7k1C4RaO3aeyJMpTs,3679
+agentic_loop-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentic_loop-0.3.0.dist-info/entry_points.txt,sha256=Vsodee_rDwrXPHx9p5DVw3Woun-0xjCozcBz1-VWjbk,55
+agentic_loop-0.3.0.dist-info/top_level.txt,sha256=sBWRV1VCNyRCzxzEyH3zSZPZ_QrCqdBkUfia0rhQ8pw,13
+agentic_loop-0.3.0.dist-info/RECORD,,

agentic_loop-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentic_loop-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentic-loop = agentic_loop.cli:main

agentic_loop-0.3.0.dist-info/licenses/LICENSE

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

agentic_loop-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentic_loop