quick-agent 0.1.1__py3-none-any.whl → 0.1.3__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

@@ -2,43 +2,23 @@
 
 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
+from quick_agent.models.loaded_agent_file import LoadedAgentFile, parse_agent_sections
 
 
 def split_step_sections(markdown_body: str) -> dict[str, str]:
     """
-    Extracts blocks that begin with headings "## step:<id>".
+    Extracts blocks that begin with headings like "# 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)
+    sections = parse_agent_sections(markdown_body)
+    return sections.step_prompts
 
 
 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
 
@@ -70,6 +50,6 @@ class AgentRegistry:
         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)
+        loaded = LoadedAgentFile(path)
         self._cache[agent_id] = loaded
         return loaded

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, and optional handoff can invoke another agent. If `output.file` is set, the final output is written to disk.
+
+**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/models/loaded_agent_file.py

@@ -2,13 +2,148 @@
 
 from __future__ import annotations
 
+import logging
+import re
 from dataclasses import dataclass
+from pathlib import Path
+
+import frontmatter
 
 from quick_agent.models.agent_spec import AgentSpec
 
 
+logger = logging.getLogger(__name__)
+
+SECTION_HEADER_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$", re.MULTILINE)
+STEP_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
 @dataclass
 class LoadedAgentFile:
     spec: AgentSpec
-    body: str
+    instructions: str
+    system_prompt: str
     step_prompts: dict[str, str]  # prompt_section -> markdown chunk
+
+    def __init__(self, agent: Path | str) -> None:
+        post, source_label = load_agent_frontmatter(agent)
+        spec = AgentSpec.model_validate(post.metadata)
+        sections = parse_agent_sections(post.content)
+        if sections.first_section_start is not None and (
+            sections.instructions_start is not None or sections.system_prompt_start is not None
+        ):
+            preamble = post.content[: sections.first_section_start]
+            if preamble.strip():
+                logger.warning("Ignored text before instructions or system prompt in %s", source_label)
+        if not sections.step_prompts and sections.instructions_start is None and sections.system_prompt_start is None:
+            raise ValueError("Agent markdown must include instructions, system prompt, or step sections.")
+        self.spec = spec
+        self.instructions = sections.instructions
+        self.system_prompt = sections.system_prompt
+        self.step_prompts = sections.step_prompts
+
+    @classmethod
+    def from_parts(
+        cls,
+        *,
+        spec: AgentSpec,
+        instructions: str,
+        system_prompt: str,
+        step_prompts: dict[str, str],
+    ) -> "LoadedAgentFile":
+        obj = cls.__new__(cls)
+        obj.spec = spec
+        obj.instructions = instructions
+        obj.system_prompt = system_prompt
+        obj.step_prompts = step_prompts
+        return obj
+
+
+@dataclass(frozen=True)
+class ParsedAgentSections:
+    instructions: str
+    system_prompt: str
+    step_prompts: dict[str, str]
+    instructions_start: int | None
+    system_prompt_start: int | None
+    first_section_start: int | None
+
+
+def load_agent_frontmatter(agent: Path | str) -> tuple[frontmatter.Post, str]:
+    if isinstance(agent, Path):
+        post = frontmatter.load(str(agent))
+        return post, str(agent)
+    agent_path = Path(agent)
+    if agent_path.exists():
+        post = frontmatter.load(str(agent_path))
+        return post, str(agent_path)
+    post = frontmatter.loads(agent)
+    return post, "<inline>"
+
+
+def normalize_header_text(header_text: str) -> str:
+    normalized = header_text.strip().lower().replace("_", " ")
+    return re.sub(r"\s+", " ", normalized)
+
+
+def classify_section_header(header_text: str) -> tuple[str, str] | None:
+    header = header_text.strip()
+    if ":" in header:
+        prefix, step_id = header.split(":", 1)
+        if prefix.strip().lower() == "step":
+            step_id = step_id.strip()
+            if step_id and STEP_ID_RE.match(step_id):
+                return ("step", f"step:{step_id}")
+    normalized = normalize_header_text(header_text)
+    if normalized == "instructions":
+        return ("instructions", "instructions")
+    if normalized == "system prompt":
+        return ("system_prompt", "system_prompt")
+    return None
+
+
+def parse_agent_sections(markdown_body: str) -> ParsedAgentSections:
+    matches = list(SECTION_HEADER_RE.finditer(markdown_body))
+    recognized: list[tuple[str, str, int, int]] = []
+    instructions_start: int | None = None
+    system_prompt_start: int | None = None
+
+    for match in matches:
+        header_text = match.group(2).strip()
+        classified = classify_section_header(header_text)
+        if classified is None:
+            continue
+        kind, key = classified
+        recognized.append((kind, key, match.start(), match.end()))
+        if kind == "instructions" and instructions_start is None:
+            instructions_start = match.start()
+        if kind == "system_prompt" and system_prompt_start is None:
+            system_prompt_start = match.start()
+
+    instructions = ""
+    system_prompt = ""
+    step_prompts: dict[str, str] = {}
+
+    for index, (kind, key, _start, end) in enumerate(recognized):
+        section_start = end
+        next_index = index + 1
+        section_end = recognized[next_index][2] if next_index < len(recognized) else len(markdown_body)
+        content = markdown_body[section_start:section_end].strip()
+        if kind == "instructions":
+            if not instructions:
+                instructions = content
+        elif kind == "system_prompt":
+            if not system_prompt:
+                system_prompt = content
+        else:
+            step_prompts[key] = content
+
+    first_section_start = recognized[0][2] if recognized else None
+    return ParsedAgentSections(
+        instructions=instructions,
+        system_prompt=system_prompt,
+        step_prompts=step_prompts,
+        instructions_start=instructions_start,
+        system_prompt_start=system_prompt_start,
+        first_section_start=first_section_start,
+    )

quick_agent/models/output_spec.py

@@ -7,4 +7,4 @@ from pydantic import BaseModel
 
 class OutputSpec(BaseModel):
     format: str = "json"  # "json" or "markdown"
-    file: str = "out/result.json"
+    file: str | None = None