quick-agent 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

quick_agent/__init__.py

@@ -1,6 +1,9 @@
 """Public package exports."""
 
+from quick_agent.input_adaptors import FileInput
+from quick_agent.input_adaptors import InputAdaptor
+from quick_agent.input_adaptors import TextInput
 from quick_agent.orchestrator import Orchestrator
 from quick_agent.quick_agent import QuickAgent
 
-__all__ = ["Orchestrator", "QuickAgent"]
+__all__ = ["FileInput", "InputAdaptor", "Orchestrator", "QuickAgent", "TextInput"]

quick_agent/agent_call_tool.py

@@ -7,11 +7,13 @@ from typing import Any, Awaitable, Callable
 
 from pydantic import BaseModel
 
+from quick_agent.input_adaptors import InputAdaptor, TextInput
+
 
 class AgentCallTool:
     def __init__(
         self,
-        call_agent: Callable[[str, Path], Awaitable[BaseModel | str]],
+        call_agent: Callable[[str, InputAdaptor | Path], Awaitable[BaseModel | str]],
         run_input_source_path: str,
     ) -> None:
         self._call_agent = call_agent
@@ -32,13 +34,28 @@ class AgentCallTool:
             path = base_dir / path
         return path
 
-    async def __call__(self, agent: str, input_file: str) -> dict[str, Any]:
+    async def __call__(
+        self,
+        agent: str,
+        input_file: str | None = None,
+        input_text: str | None = None,
+    ) -> dict[str, Any]:
         """
-        Call another agent by ID with an input file path.
+        Call another agent by ID with an input file path or inline text.
         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 input_file and input_text:
+            raise ValueError("Provide only one of input_file or input_text.")
+        if not input_file and input_text is None:
+            raise ValueError("Provide either input_file or input_text.")
+        if input_text is not None:
+            input_data: InputAdaptor | Path = TextInput(input_text)
+        else:
+            if input_file is None:
+                raise ValueError("Provide either input_file or input_text.")
+            resolved_input = self._resolve_input_file(input_file)
+            input_data = resolved_input
+        out = await self._call_agent(agent, input_data)
         if isinstance(out, BaseModel):
             return out.model_dump()
         return {"text": out}

quick_agent/agent_registry.py

@@ -37,8 +37,8 @@ def load_agent_file(path: Path) -> LoadedAgentFile:
 
 
 class AgentRegistry:
-    def __init__(self, agent_roots: list[Path]):
-        self.agent_roots = agent_roots
+    def __init__(self, agent_roots: list[Path]) -> None:
+        self.agent_roots: list[Path] = agent_roots
         self._cache: dict[str, LoadedAgentFile] = {}
         self._index: dict[str, Path] | None = None
 

quick_agent/agent_tools.py

@@ -10,12 +10,13 @@ from pydantic_ai.toolsets import FunctionToolset
 
 from quick_agent.agent_call_tool import AgentCallTool
 from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.input_adaptors import InputAdaptor
 from quick_agent.tools_loader import load_tools
 
 
 class AgentTools:
     def __init__(self, tool_roots: list[Path]) -> None:
-        self._tool_roots = tool_roots
+        self._tool_roots: list[Path] = 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"]
@@ -28,7 +29,7 @@ class AgentTools:
         tool_ids: list[str],
         toolset: FunctionToolset[Any],
         run_input_source_path: str,
-        call_agent: Callable[[str, Path], Awaitable[BaseModel | str]],
+        call_agent: Callable[[str, InputAdaptor | Path], Awaitable[BaseModel | str]],
     ) -> None:
         if "agent.call" not in tool_ids:
             return

quick_agent/cli.py

@@ -7,16 +7,28 @@ from pathlib import Path
 
 from pydantic import BaseModel
 
+from quick_agent.input_adaptors import InputAdaptor, TextInput
 from quick_agent.orchestrator import Orchestrator
 
 
+async def run_agent(
+    orch: Orchestrator,
+    agent_id: str,
+    input_adaptor: InputAdaptor | Path,
+    extra_tools: list[str],
+) -> BaseModel | str:
+    return await orch.run(agent_id, input_adaptor, extra_tools=extra_tools)
+
+
 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)
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("--input", type=str, help="Path to an input file")
+    input_group.add_argument("--input-text", type=str, help="Raw input text")
     parser.add_argument("--tool", action="append", default=[], help="Extra tool IDs to add at runtime")
     args = parser.parse_args()
 
@@ -30,14 +42,16 @@ def main() -> None:
     tool_roots = [user_tools_dir, system_tools_dir]
 
     orch = Orchestrator(agent_roots, tool_roots, Path(args.safe_dir))
+    input_adaptor: InputAdaptor | Path
+    if args.input_text is not None:
+        input_adaptor = TextInput(args.input_text)
+    else:
+        input_adaptor = Path(args.input)
 
     # Async entrypoint
     import anyio
 
-    async def runner():
-        return await orch.run(args.agent, Path(args.input), extra_tools=args.tool)
-
-    out = anyio.run(runner)
+    out = anyio.run(run_agent, orch, args.agent, input_adaptor, args.tool)
     if isinstance(out, BaseModel):
         print(out.model_dump_json(indent=2))
     else:

quick_agent/directory_permissions.py

@@ -6,14 +6,16 @@ from pathlib import Path
 
 
 class DirectoryPermissions:
-    def __init__(self, root: Path) -> None:
-        self._root = root.expanduser().resolve(strict=False)
+    def __init__(self, root: Path | None) -> None:
+        self._root = root.expanduser().resolve(strict=False) if root is not None else None
 
     @property
-    def root(self) -> Path:
+    def root(self) -> Path | None:
         return self._root
 
     def scoped(self, directory: str | None) -> "DirectoryPermissions":
+        if self._root is None:
+            return self
         if directory:
             candidate = (self._root / directory).expanduser().resolve(strict=False)
             root_resolved = self._root.expanduser().resolve(strict=False)
@@ -23,6 +25,8 @@ class DirectoryPermissions:
         return self
 
     def resolve(self, path: Path, *, for_write: bool) -> Path:
+        if self._root is None:
+            raise PermissionError("No safe directory configured; reads and writes are denied.")
         target = path
         if not target.is_absolute():
             target = self._root / target

quick_agent/input_adaptors.py

@@ -0,0 +1,30 @@
+"""Input adaptors for agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.io_utils import load_input
+from quick_agent.models.run_input import RunInput
+
+
+class InputAdaptor:
+    def load(self) -> RunInput:
+        raise NotImplementedError("InputAdaptor.load must be implemented by subclasses.")
+
+
+class FileInput(InputAdaptor):
+    def __init__(self, path: Path, permissions: DirectoryPermissions) -> None:
+        self._run_input = load_input(path, permissions)
+
+    def load(self) -> RunInput:
+        return self._run_input
+
+
+class TextInput(InputAdaptor):
+    def __init__(self, text: str) -> None:
+        self._text = text
+
+    def load(self) -> RunInput:
+        return RunInput(source_path="inline_input.txt", kind="text", text=self._text, data=None)

quick_agent/llms.txt

@@ -0,0 +1,239 @@
+# Quick Agent (llms.txt)
+
+**Project Summary**
+- Quick Agent is a minimal, local-first agent runner that loads agent definitions from Markdown front matter and executes a small chain of steps with bounded context.
+- Agents are Markdown files with YAML front matter for model/tools/chain and `## step:<id>` sections for prompts.
+- Execution is deterministic: steps run in order, state stores prior step outputs, final output is written to disk, and optional handoff can invoke another agent.
+
+**Primary Entry Points**
+- CLI: `quick-agent --agent <id> --input <path>` (module: `quick_agent.cli:main`).
+- Python API: `quick_agent.orchestrator.Orchestrator` and `quick_agent.quick_agent.QuickAgent`.
+
+**How It Works (High Level)**
+- Agent files are loaded by `AgentRegistry` from user and packaged directories.
+- `QuickAgent` loads the agent spec, scopes file permissions, builds the toolset, then runs each chain step (text or structured).
+- Structured steps validate JSON output against a Pydantic schema and attempt extraction if the raw output contains extra text.
+- Outputs are written via `io_utils.write_output` and constrained by `DirectoryPermissions`.
+- Input handling uses adaptors: file inputs are permission-checked at creation, and text inputs bypass filesystem access.
+
+**Key Files**
+- `src/quick_agent/quick_agent.py`: core execution engine and step handling.
+- `src/quick_agent/orchestrator.py`: convenience wrapper for running agents.
+- `src/quick_agent/agent_registry.py`: loads agent Markdown files.
+- `src/quick_agent/agent_tools.py`: loads tools and builds the toolset.
+- `src/quick_agent/directory_permissions.py`: enforces safe directory access.
+- `src/quick_agent/tools/**/tool.json`: tool definitions (id, module, function).
+- `agents/`: example agents shipped with the repo.
+- `docs/`: CLI, template, and Python usage documentation.
+
+**Agent File Format (Essentials)**
+- Required fields: `name`, `model.base_url`, `model.model_name`, `chain`.
+- Each `chain` step must reference a matching `## step:<id>` section in the body.
+- Tools are referenced by id and resolved from `tool.json` definitions.
+- `safe_dir` must be relative and further scopes file access inside the CLI safe root.
+
+**Safety and Permissions**
+- File reads and writes are restricted to a safe directory configured by `--safe-dir` (default `safe`).
+- Agent-level `safe_dir` can further restrict access to a subdirectory.
+- If no safe directory is configured, all reads and writes are denied.
+
+**Tests**
+- Tests live in `src/tests`.
+- Run with `pytest` (requires optional dependency group `test`).
+
+**Useful Docs**
+- `docs/cli.md`: CLI usage and options.
+- `docs/templates.md`: agent template format and examples.
+- `docs/python.md`: embedding the orchestrator and inter-agent calls.
+- `docs/state.md`: how chain state is stored and used.
+
+**Mini Example Agent**
+```markdown
+---
+name: "Hello Agent"
+description: "Minimal example"
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OPENAI_API_KEY"
+  model_name: "llama3"
+chain:
+  - id: hello
+    kind: text
+    prompt_section: step:hello
+output:
+  format: json
+  file: out/hello.json
+---
+
+## step:hello
+
+Say hello to the input.
+```
+
+**Mini Example (Structured Output)**
+```markdown
+---
+name: "Structured Agent"
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OPENAI_API_KEY"
+  model_name: "llama3"
+schemas:
+  Summary: "quick_agent.schemas.outputs:SummaryOutput"
+chain:
+  - id: summarize
+    kind: structured
+    prompt_section: step:summarize
+    output_schema: Summary
+output:
+  format: json
+  file: out/summary.json
+---
+
+## step:summarize
+
+Summarize the input into a short title and 2 bullet points.
+```
+
+**Schema Snippet (for Structured Output)**
+```python
+from pydantic import BaseModel
+
+
+class SummaryOutput(BaseModel):
+    title: str
+    bullets: list[str]
+```
+
+**Input Adaptors (Python)**
+```python
+from pathlib import Path
+
+from quick_agent import FileInput
+from quick_agent import Orchestrator
+from quick_agent import TextInput
+
+orchestrator = Orchestrator([Path("agents")], [Path("tools")], safe_dir=Path("safe"))
+
+file_input = FileInput(Path("safe/input.txt"), orchestrator.directory_permissions)
+text_input = TextInput("hello from memory")
+
+result_from_file = await orchestrator.run("example", file_input)
+result_from_text = await orchestrator.run("example", text_input)
+```
+
+**Multi-Step Example (State + Structured Output)**
+```markdown
+---
+name: "Draft And Summarize"
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OPENAI_API_KEY"
+  model_name: "llama3"
+schemas:
+  Summary: "quick_agent.schemas.outputs:SummaryOutput"
+chain:
+  - id: draft
+    kind: text
+    prompt_section: step:draft
+  - id: summarize
+    kind: structured
+    prompt_section: step:summarize
+    output_schema: Summary
+output:
+  format: json
+  file: out/draft_summary.json
+---
+
+## step:draft
+
+Write a short draft based on the input.
+
+## step:summarize
+
+Summarize the draft from state as a title and 2 bullets.
+Use the value at state.steps.draft.
+```
+
+**Inter-Agent Call Example (agent.call)**
+```markdown
+---
+name: "Parent Agent"
+tools:
+  - "agent.call"
+nested_output: inline
+chain:
+  - id: invoke_child
+    kind: text
+    prompt_section: step:invoke_child
+output:
+  format: json
+  file: out/parent.json
+---
+
+## step:invoke_child
+
+Call agent_call with agent "child" and input_file "{base_directory}/child_input.txt".
+Then respond with only the returned text value.
+```
+
+```markdown
+---
+name: "Child Agent"
+chain:
+  - id: respond
+    kind: text
+    prompt_section: step:respond
+output:
+  format: json
+  file: out/child.json
+---
+
+## step:respond
+
+Reply with exactly: pong
+```
+
+Nested calls default to `nested_output: inline`, so the child agent above will not write
+`out/child.json` unless the parent sets `nested_output: file`.
+
+**Handoff Example (Run Another Agent After Output)**
+```markdown
+---
+name: "Writer With Handoff"
+chain:
+  - id: write
+    kind: text
+    prompt_section: step:write
+output:
+  format: json
+  file: out/writer.json
+handoff:
+  enabled: true
+  agent_id: "reviewer"
+---
+
+## step:write
+
+Write a short answer to the input.
+```
+
+```markdown
+---
+name: "Reviewer"
+chain:
+  - id: review
+    kind: text
+    prompt_section: step:review
+output:
+  format: json
+  file: out/reviewer.json
+---
+
+## step:review
+
+Review the inline output produced by the writer and provide a brief critique.
+```

quick_agent/models/agent_spec.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, Field
 
 from quick_agent.models.chain_step_spec import ChainStepSpec
@@ -19,4 +21,5 @@ class AgentSpec(BaseModel):
     chain: list[ChainStepSpec]
     output: OutputSpec = Field(default_factory=OutputSpec)
     handoff: HandoffSpec = Field(default_factory=HandoffSpec)
+    nested_output: Literal["inline", "file"] = "inline"
     safe_dir: str | None = None

quick_agent/orchestrator.py

@@ -3,33 +3,40 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Optional
 
 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.input_adaptors import InputAdaptor
 from quick_agent.quick_agent import QuickAgent
 
 
 class Orchestrator:
     def __init__(
         self,
-        agent_roots: list[Path],
-        tool_roots: list[Path],
-        safe_dir: Path,
+        agent_roots: list[Path] | None = None,
+        tool_roots: list[Path] | None = None,
+        safe_dir: Optional[Path] = None,
     ) -> None:
-        self.registry = AgentRegistry(agent_roots)
-        self.tools = AgentTools(tool_roots)
-        self.directory_permissions = DirectoryPermissions(safe_dir)
+        self.registry: AgentRegistry = AgentRegistry(agent_roots or [])
+        self.tools: AgentTools = AgentTools(tool_roots or [])
+        self.directory_permissions: DirectoryPermissions = DirectoryPermissions(safe_dir)
 
-    async def run(self, agent_id: str, input_path: Path, extra_tools: list[str] | None = None) -> BaseModel | str:
+    async def run(
+        self,
+        agent_id: str,
+        input_data: InputAdaptor | 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,
+            input_data=input_data,
             extra_tools=extra_tools,
         )
         return await agent.run()

quick_agent/prompting.py

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import Any, Mapping
 
 from quick_agent.models.run_input import RunInput
 
 
-def make_user_prompt(step_prompt: str, run_input: RunInput, state: dict[str, Any]) -> str:
+def make_user_prompt(step_prompt: str, run_input: RunInput, state: Mapping[str, Any]) -> str:
     """
     Creates a consistent user prompt payload. Consistency helps prefix-caching backends.
     """

quick_agent/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 type hints.