quick-agent 0.1.1__py3-none-any.whl

quick_agent/__init__.py

@@ -0,0 +1,6 @@
+"""Public package exports."""
+
+from quick_agent.orchestrator import Orchestrator
+from quick_agent.quick_agent import QuickAgent
+
+__all__ = ["Orchestrator", "QuickAgent"]

quick_agent/agent_call_tool.py

@@ -0,0 +1,44 @@
+"""Callable tool for inter-agent calls."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from pydantic import BaseModel
+
+
+class AgentCallTool:
+    def __init__(
+        self,
+        call_agent: Callable[[str, Path], Awaitable[BaseModel | str]],
+        run_input_source_path: str,
+    ) -> None:
+        self._call_agent = call_agent
+        self._run_input_source_path = run_input_source_path
+        self.__name__ = "agent_call"
+
+    def _resolve_input_file(self, raw_input_file: str) -> Path:
+        cleaned = raw_input_file.strip()
+        if (
+            (cleaned.startswith("\"") and cleaned.endswith("\""))
+            or (cleaned.startswith("'") and cleaned.endswith("'"))
+        ):
+            cleaned = cleaned[1:-1]
+        base_dir = Path(self._run_input_source_path).parent
+        cleaned = cleaned.replace("{base_directory}", str(base_dir))
+        path = Path(cleaned)
+        if not path.is_absolute():
+            path = base_dir / path
+        return path
+
+    async def __call__(self, agent: str, input_file: str) -> dict[str, Any]:
+        """
+        Call another agent by ID with an input file path.
+        Returns JSON-serializable dict output if structured, else {"text": "..."}.
+        """
+        resolved_input = self._resolve_input_file(input_file)
+        out = await self._call_agent(agent, resolved_input)
+        if isinstance(out, BaseModel):
+            return out.model_dump()
+        return {"text": out}

quick_agent/agent_registry.py

@@ -0,0 +1,75 @@
+"""Agent registry and parsing utilities."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import frontmatter
+
+from quick_agent.models.agent_spec import AgentSpec
+from quick_agent.models.loaded_agent_file import LoadedAgentFile
+
+
+def split_step_sections(markdown_body: str) -> dict[str, str]:
+    """
+    Extracts blocks that begin with headings "## step:<id>".
+    Returns mapping: "step:<id>" -> content for that step (excluding heading line).
+    """
+    pattern = re.compile(r"^##\s+(step:[A-Za-z0-9_\-]+)\s*$", re.MULTILINE)
+    matches = list(pattern.finditer(markdown_body))
+    out: dict[str, str] = {}
+
+    for i, m in enumerate(matches):
+        section_name = m.group(1)
+        start = m.end()
+        end = matches[i + 1].start() if (i + 1) < len(matches) else len(markdown_body)
+        out[section_name] = markdown_body[start:end].strip()
+
+    return out
+
+
+def load_agent_file(path: Path) -> LoadedAgentFile:
+    post = frontmatter.load(str(path))
+    spec = AgentSpec.model_validate(post.metadata)
+    steps = split_step_sections(post.content)
+    return LoadedAgentFile(spec=spec, body=post.content, step_prompts=steps)
+
+
+class AgentRegistry:
+    def __init__(self, agent_roots: list[Path]):
+        self.agent_roots = agent_roots
+        self._cache: dict[str, LoadedAgentFile] = {}
+        self._index: dict[str, Path] | None = None
+
+    def _build_index(self) -> dict[str, Path]:
+        index: dict[str, Path] = {}
+        for root in self.agent_roots:
+            if not root.exists():
+                continue
+            for path in root.rglob("*.md"):
+                agent_id = path.stem
+                if agent_id in index:
+                    continue
+                index[agent_id] = path
+        return index
+
+    def _get_index(self) -> dict[str, Path]:
+        if self._index is None:
+            self._index = self._build_index()
+        return self._index
+
+    def list_agents(self) -> list[str]:
+        index = self._get_index()
+        return sorted(index.keys())
+
+    def get(self, agent_id: str) -> LoadedAgentFile:
+        if agent_id in self._cache:
+            return self._cache[agent_id]
+        index = self._get_index()
+        path = index.get(agent_id)
+        if path is None:
+            raise FileNotFoundError(f"Agent not found: {agent_id} (searched: {self.agent_roots})")
+        loaded = load_agent_file(path)
+        self._cache[agent_id] = loaded
+        return loaded

quick_agent/agent_tools.py

@@ -0,0 +1,41 @@
+"""Toolset builder and agent-call injection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from pydantic import BaseModel
+from pydantic_ai.toolsets import FunctionToolset
+
+from quick_agent.agent_call_tool import AgentCallTool
+from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.tools_loader import load_tools
+
+
+class AgentTools:
+    def __init__(self, tool_roots: list[Path]) -> None:
+        self._tool_roots = tool_roots
+
+    def build_toolset(self, tool_ids: list[str], permissions: DirectoryPermissions) -> FunctionToolset[Any]:
+        tool_ids_for_disk = [tool_id for tool_id in tool_ids if tool_id != "agent.call"]
+        if tool_ids_for_disk:
+            return load_tools(self._tool_roots, tool_ids_for_disk, permissions)
+        return FunctionToolset()
+
+    def maybe_inject_agent_call(
+        self,
+        tool_ids: list[str],
+        toolset: FunctionToolset[Any],
+        run_input_source_path: str,
+        call_agent: Callable[[str, Path], Awaitable[BaseModel | str]],
+    ) -> None:
+        if "agent.call" not in tool_ids:
+            return
+
+        tool = AgentCallTool(call_agent, run_input_source_path)
+        toolset.add_function(
+            func=tool.__call__,
+            name="agent_call",
+            description="Call another agent and return its output.",
+        )

quick_agent/cli.py

@@ -0,0 +1,44 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from quick_agent.orchestrator import Orchestrator
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--agents-dir", type=str, default="agents")
+    parser.add_argument("--tools-dir", type=str, default="tools")
+    parser.add_argument("--safe-dir", type=str, default="safe")
+    parser.add_argument("--agent", type=str, required=True)
+    parser.add_argument("--input", type=str, required=True)
+    parser.add_argument("--tool", action="append", default=[], help="Extra tool IDs to add at runtime")
+    args = parser.parse_args()
+
+    package_root = Path(__file__).resolve().parent
+    system_agents_dir = package_root / "agents"
+    system_tools_dir = package_root / "tools"
+    user_agents_dir = Path(args.agents_dir)
+    user_tools_dir = Path(args.tools_dir)
+
+    agent_roots = [user_agents_dir, system_agents_dir]
+    tool_roots = [user_tools_dir, system_tools_dir]
+
+    orch = Orchestrator(agent_roots, tool_roots, Path(args.safe_dir))
+
+    # Async entrypoint
+    import anyio
+
+    async def runner():
+        return await orch.run(args.agent, Path(args.input), extra_tools=args.tool)
+
+    out = anyio.run(runner)
+    if isinstance(out, BaseModel):
+        print(out.model_dump_json(indent=2))
+    else:
+        print(out)

quick_agent/directory_permissions.py

@@ -0,0 +1,49 @@
+"""Directory permission enforcement for file access."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class DirectoryPermissions:
+    def __init__(self, root: Path) -> None:
+        self._root = root.expanduser().resolve(strict=False)
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def scoped(self, directory: str | None) -> "DirectoryPermissions":
+        if directory:
+            candidate = (self._root / directory).expanduser().resolve(strict=False)
+            root_resolved = self._root.expanduser().resolve(strict=False)
+            if not candidate.is_relative_to(root_resolved):
+                raise ValueError(f"Scoped directory {directory!r} escapes safe root {root_resolved}.")
+            return DirectoryPermissions(candidate)
+        return self
+
+    def resolve(self, path: Path, *, for_write: bool) -> Path:
+        target = path
+        if not target.is_absolute():
+            target = self._root / target
+        resolved = target.expanduser().resolve(strict=False)
+        root_resolved = self._root.expanduser().resolve(strict=False)
+        if not resolved.is_relative_to(root_resolved):
+            raise PermissionError(f"Path {resolved} is outside safe directory {root_resolved}.")
+        if for_write:
+            root_resolved.mkdir(parents=True, exist_ok=True)
+        return resolved
+
+    def can_read(self, path: Path) -> bool:
+        try:
+            self.resolve(path, for_write=False)
+        except PermissionError:
+            return False
+        return True
+
+    def can_write(self, path: Path) -> bool:
+        try:
+            self.resolve(path, for_write=False)
+        except PermissionError:
+            return False
+        return True

quick_agent/io_utils.py

@@ -0,0 +1,36 @@
+"""Input/output helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.models.run_input import RunInput
+
+
+def load_input(path: Path, permissions: DirectoryPermissions) -> RunInput:
+    safe_path = permissions.resolve(path, for_write=False)
+    if not safe_path.exists():
+        raise FileNotFoundError(safe_path)
+
+    if safe_path.suffix.lower() == ".json":
+        raw = json.loads(safe_path.read_text(encoding="utf-8"))
+        return RunInput(source_path=str(safe_path), kind="json", text=json.dumps(raw, indent=2), data=raw)
+    txt = safe_path.read_text(encoding="utf-8")
+    return RunInput(source_path=str(safe_path), kind="text", text=txt, data=None)
+
+
+def ensure_parent_dir(path: Path, permissions: DirectoryPermissions) -> Path:
+    safe_path = permissions.resolve(path, for_write=True)
+    safe_path.parent.mkdir(parents=True, exist_ok=True)
+    return safe_path
+
+
+def write_output(
+    path: Path,
+    content: str,
+    permissions: DirectoryPermissions,
+) -> None:
+    safe_path = ensure_parent_dir(path, permissions)
+    safe_path.write_text(content, encoding="utf-8")

quick_agent/json_utils.py

@@ -0,0 +1,37 @@
+"""JSON parsing helpers."""
+
+from __future__ import annotations
+
+
+def extract_first_json_object(text: str) -> str:
+    """
+    Extract the first top-level JSON object from text.
+    This is a fallback for models that wrap JSON in extra text.
+    """
+    start = text.find("{")
+    if start == -1:
+        raise ValueError("No JSON object found in model output.")
+
+    depth = 0
+    in_string = False
+    escape = False
+    for i in range(start, len(text)):
+        ch = text[i]
+        if in_string:
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == "\"":
+                in_string = False
+        else:
+            if ch == "\"":
+                in_string = True
+            elif ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    return text[start : i + 1]
+
+    raise ValueError("Unbalanced JSON object in model output.")

quick_agent/models/__init__.py

@@ -0,0 +1,23 @@
+"""Model types for agent configuration and runtime."""
+
+from quick_agent.models.agent_spec import AgentSpec
+from quick_agent.models.chain_step_spec import ChainStepSpec
+from quick_agent.models.handoff_spec import HandoffSpec
+from quick_agent.models.loaded_agent_file import LoadedAgentFile
+from quick_agent.models.model_spec import ModelSpec
+from quick_agent.models.output_spec import OutputSpec
+from quick_agent.models.run_input import RunInput
+from quick_agent.models.tool_impl_spec import ToolImplSpec
+from quick_agent.models.tool_json import ToolJson
+
+__all__ = [
+    "AgentSpec",
+    "ChainStepSpec",
+    "HandoffSpec",
+    "LoadedAgentFile",
+    "ModelSpec",
+    "OutputSpec",
+    "RunInput",
+    "ToolImplSpec",
+    "ToolJson",
+]

quick_agent/models/agent_spec.py

@@ -0,0 +1,22 @@
+"""Pydantic model for agent frontmatter spec."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from quick_agent.models.chain_step_spec import ChainStepSpec
+from quick_agent.models.handoff_spec import HandoffSpec
+from quick_agent.models.model_spec import ModelSpec
+from quick_agent.models.output_spec import OutputSpec
+
+
+class AgentSpec(BaseModel):
+    name: str
+    description: str = ""
+    model: ModelSpec = Field(default_factory=ModelSpec)
+    tools: list[str] = Field(default_factory=list)
+    schemas: dict[str, str] = Field(default_factory=dict)  # alias -> "module:ClassName"
+    chain: list[ChainStepSpec]
+    output: OutputSpec = Field(default_factory=OutputSpec)
+    handoff: HandoffSpec = Field(default_factory=HandoffSpec)
+    safe_dir: str | None = None

quick_agent/models/chain_step_spec.py

@@ -0,0 +1,14 @@
+"""Pydantic model for a single chain step."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class ChainStepSpec(BaseModel):
+    id: str
+    kind: str  # "text" or "structured" (you may extend: "parallel_map", "fanout", etc.)
+    prompt_section: str
+    output_schema: Optional[str] = None

quick_agent/models/handoff_spec.py

@@ -0,0 +1,13 @@
+"""Pydantic model for handoff configuration."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class HandoffSpec(BaseModel):
+    enabled: bool = False
+    agent_id: Optional[str] = None
+    input_mode: str = "final_output_json"

quick_agent/models/loaded_agent_file.py

@@ -0,0 +1,14 @@
+"""Loaded agent markdown plus parsed metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from quick_agent.models.agent_spec import AgentSpec
+
+
+@dataclass
+class LoadedAgentFile:
+    spec: AgentSpec
+    body: str
+    step_prompts: dict[str, str]  # prompt_section -> markdown chunk

quick_agent/models/model_spec.py

@@ -0,0 +1,14 @@
+"""Pydantic model for LLM configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelSpec(BaseModel):
+    provider: str = Field(default="openai-compatible")
+    base_url: str = Field(default="https://api.openai.com/v1")
+    api_key_env: str = Field(default="OPENAI_API_KEY")
+    model_name: str = Field(default="gpt-5.2")
+    temperature: float = 0.2
+    max_tokens: int = 2048

quick_agent/models/output_spec.py

@@ -0,0 +1,10 @@
+"""Pydantic model for output configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class OutputSpec(BaseModel):
+    format: str = "json"  # "json" or "markdown"
+    file: str = "out/result.json"

quick_agent/models/run_input.py

@@ -0,0 +1,14 @@
+"""Pydantic model for runtime input."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+
+class RunInput(BaseModel):
+    source_path: str
+    kind: str  # "json" or "text"
+    text: str
+    data: Optional[dict[str, Any]] = None

quick_agent/models/tool_impl_spec.py

@@ -0,0 +1,11 @@
+"""Pydantic model for tool implementation metadata."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ToolImplSpec(BaseModel):
+    kind: str  # "python"
+    module: str
+    function: str

quick_agent/models/tool_json.py

@@ -0,0 +1,14 @@
+"""Pydantic model for tool.json files."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from quick_agent.models.tool_impl_spec import ToolImplSpec
+
+
+class ToolJson(BaseModel):
+    id: str
+    name: str
+    description: str = ""
+    impl: ToolImplSpec

quick_agent/orchestrator.py

@@ -0,0 +1,35 @@
+"""Helper for running agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from quick_agent.agent_registry import AgentRegistry
+from quick_agent.agent_tools import AgentTools
+from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.quick_agent import QuickAgent
+
+
+class Orchestrator:
+    def __init__(
+        self,
+        agent_roots: list[Path],
+        tool_roots: list[Path],
+        safe_dir: Path,
+    ) -> None:
+        self.registry = AgentRegistry(agent_roots)
+        self.tools = AgentTools(tool_roots)
+        self.directory_permissions = DirectoryPermissions(safe_dir)
+
+    async def run(self, agent_id: str, input_path: Path, extra_tools: list[str] | None = None) -> BaseModel | str:
+        agent = QuickAgent(
+            registry=self.registry,
+            tools=self.tools,
+            directory_permissions=self.directory_permissions,
+            agent_id=agent_id,
+            input_path=input_path,
+            extra_tools=extra_tools,
+        )
+        return await agent.run()

quick_agent/prompting.py

@@ -0,0 +1,28 @@
+"""Prompt composition helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from quick_agent.models.run_input import RunInput
+
+
+def make_user_prompt(step_prompt: str, run_input: RunInput, state: dict[str, Any]) -> str:
+    """
+    Creates a consistent user prompt payload. Consistency helps prefix-caching backends.
+    """
+    # Keep the preamble stable; append variable fields below.
+    return f"""# Task Input
+source_path: {run_input.source_path}
+kind: {run_input.kind}
+
+## Input Content
+{run_input.text}
+
+## Chain State (JSON)
+{json.dumps(state, indent=2)}
+
+## Step Instructions
+{step_prompt}
+"""