quick-agent 0.1.1__tar.gz → 0.1.3__tar.gz

{quick_agent-0.1.1 → quick_agent-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick-agent
-Version: 0.1.1
+Version: 0.1.3
 Summary: Minimal, local-first agent runner using Markdown front matter.
 Author-email: Charles Verge <1906614+charlesverge@users.noreply.github.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -700,6 +700,8 @@ Requires-Dist: anyio
 Requires-Dist: pydantic
 Requires-Dist: pydantic-ai
 Requires-Dist: python-frontmatter
+Requires-Dist: types-PyYAML
+Requires-Dist: PyYAML
 Provides-Extra: dev
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -707,13 +709,14 @@ Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Dynamic: license-file
 
-# Simple Agent
+# Quick Agent
 
-Simple Agent is a minimal, local-first agent runner that loads agent definitions from Markdown front matter and executes a small chain of steps with limited context handling. It is intentionally small and explicit: you define the model, tools, and steps in a single Markdown file, and the orchestrator runs those steps in order with a bounded prompt preamble.
+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 limited context handling. It is intentionally small and explicit: you define the model, tools, and steps in a single Markdown file, and the orchestrator runs those steps in order with a bounded prompt preamble.
 
 ## Project Goal
 
 Provide a simple, maintainable agent framework that:
+
 - Uses Markdown front matter for agent configuration.
 - Runs a deterministic chain of steps (text or structured output).
 - Keeps context handling deliberately limited and predictable.
@@ -887,7 +890,7 @@ def main() -> None:
         tools=tools,
         directory_permissions=permissions,
         agent_id="hello",
-        input_path=Path("safe/path/to/input.txt"),
+        input_data=Path("safe/path/to/input.txt"),
         extra_tools=None,
     )
 
@@ -907,6 +910,18 @@ Agents are stored as Markdown files with YAML front matter and step sections:
 - Body contains `## step:<id>` sections referenced by the chain.
 
 The orchestrator loads the agent, builds the tools, and executes each step in order, writing the final output to disk.
+If the agent front matter omits `output.file`, the orchestrator returns the final output without writing a file.
+
+## Nested Output
+
+When an agent invokes another agent via `agent_call` or `handoff`, the nested agent can either write its
+own `output.file` or return output inline only. Configure this in the parent agent front matter:
+
+```yaml
+nested_output: inline  # default, no output file for nested calls
+```
+
+Use `nested_output: file` to allow nested agents to write their configured output files.
 
 ## Documentation
 
@@ -914,5 +929,7 @@ See the docs in `docs/`:
 
 - [docs/cli.md](docs/cli.md): Command line usage and options.
 - [docs/templates.md](docs/templates.md): Agent template format and examples.
+- [docs/outputs.md](docs/outputs.md): Output configuration and behavior.
 - [docs/python.md](docs/python.md): Embedding the orchestrator in scripts.
 - [docs/python.md#inter-agent-calls](docs/python.md#inter-agent-calls): Example of one agent calling another.
+- [src/quick_agent/llms.txt](src/quick_agent/llms.txt): LLM-oriented project summary and examples.

{quick_agent-0.1.1 → quick_agent-0.1.3}/README.md

@@ -1,10 +1,11 @@
-# Simple Agent
+# Quick Agent
 
-Simple Agent is a minimal, local-first agent runner that loads agent definitions from Markdown front matter and executes a small chain of steps with limited context handling. It is intentionally small and explicit: you define the model, tools, and steps in a single Markdown file, and the orchestrator runs those steps in order with a bounded prompt preamble.
+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 limited context handling. It is intentionally small and explicit: you define the model, tools, and steps in a single Markdown file, and the orchestrator runs those steps in order with a bounded prompt preamble.
 
 ## Project Goal
 
 Provide a simple, maintainable agent framework that:
+
 - Uses Markdown front matter for agent configuration.
 - Runs a deterministic chain of steps (text or structured output).
 - Keeps context handling deliberately limited and predictable.
@@ -178,7 +179,7 @@ def main() -> None:
         tools=tools,
         directory_permissions=permissions,
         agent_id="hello",
-        input_path=Path("safe/path/to/input.txt"),
+        input_data=Path("safe/path/to/input.txt"),
         extra_tools=None,
     )
 
@@ -198,6 +199,18 @@ Agents are stored as Markdown files with YAML front matter and step sections:
 - Body contains `## step:<id>` sections referenced by the chain.
 
 The orchestrator loads the agent, builds the tools, and executes each step in order, writing the final output to disk.
+If the agent front matter omits `output.file`, the orchestrator returns the final output without writing a file.
+
+## Nested Output
+
+When an agent invokes another agent via `agent_call` or `handoff`, the nested agent can either write its
+own `output.file` or return output inline only. Configure this in the parent agent front matter:
+
+```yaml
+nested_output: inline  # default, no output file for nested calls
+```
+
+Use `nested_output: file` to allow nested agents to write their configured output files.
 
 ## Documentation
 
@@ -205,5 +218,7 @@ See the docs in `docs/`:
 
 - [docs/cli.md](docs/cli.md): Command line usage and options.
 - [docs/templates.md](docs/templates.md): Agent template format and examples.
+- [docs/outputs.md](docs/outputs.md): Output configuration and behavior.
 - [docs/python.md](docs/python.md): Embedding the orchestrator in scripts.
 - [docs/python.md#inter-agent-calls](docs/python.md#inter-agent-calls): Example of one agent calling another.
+- [src/quick_agent/llms.txt](src/quick_agent/llms.txt): LLM-oriented project summary and examples.

quick_agent-0.1.3/agents/business-extract-structured.md

@@ -0,0 +1,49 @@
+---
+name: "Business Extract Structured"
+description: "Extract company name, location, and summary into structured JSON."
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OPENAI_API_KEY"
+  model_name: "llama3"
+schemas:
+  BusinessSummary: "quick_agent.schemas.outputs:BusinessSummary"
+chain:
+  - id: company_name
+    kind: text
+    prompt_section: step:company_name
+  - id: location
+    kind: text
+    prompt_section: step:location
+  - id: summary
+    kind: structured
+    prompt_section: step:summary
+    output_schema: BusinessSummary
+output:
+  format: "json"
+  file: "out/business_extract_structured.json"
+---
+
+## Instructions
+
+Extract structured details from the input description.
+
+## step:company_name
+
+Extract the company name from the input description.
+Return only the company name.
+
+## step:location
+
+Extract the location from the input description.
+If a city and region are present, include both.
+Return only the location.
+
+## step:summary
+
+Return a JSON object with:
+- `company_name`
+- `location`
+- `summary` (one sentence)
+
+Use `state.steps.company_name` and `state.steps.location` for the fields if available.

quick_agent-0.1.3/agents/business-extract.md

@@ -0,0 +1,42 @@
+---
+name: "Business Extract"
+description: "Extract company name, location, and a short summary from a business description."
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OPENAI_API_KEY"
+  model_name: "llama3"
+chain:
+  - id: company_name
+    kind: text
+    prompt_section: step:company_name
+  - id: location
+    kind: text
+    prompt_section: step:location
+  - id: summary
+    kind: text
+    prompt_section: step:summary
+output:
+  format: "markdown"
+  file: "out/business_extract.md"
+---
+
+## Instructions
+
+Extract structured details from the input description.
+
+## step:company_name
+
+Extract the company name from the input description.
+Return only the company name.
+
+## step:location
+
+Extract the location from the input description.
+If a city and region are present, include both.
+Return only the location.
+
+## step:summary
+
+Write one sentence summarizing the business.
+Use `state.steps.company_name` and `state.steps.location` if available.

{quick_agent-0.1.1 → quick_agent-0.1.3}/agents/function-spec-validator.md

@@ -43,7 +43,7 @@ handoff:
   input_mode: "final_output_json"
 ---
 
-# function_spec_validator
+## Instructions
 
 You are a validation agent that checks a provided function specification.
 Return a JSON valid result that includes a boolean `valid` field.

{quick_agent-0.1.1 → quick_agent-0.1.3}/agents/subagent-validate-eval-list.md

@@ -49,7 +49,7 @@ handoff:
   input_mode: "final_output_json"
 ---
 
-# subagent-validate-eval-list
+## Instructions
 
 You are an EVAL LIST EXECUTOR. Your sole responsibility is reading an eval list file, executing each test agent, validating responses, and producing a results summary. You do NOT perform the tasks yourself—you delegate them entirely.
 

{quick_agent-0.1.1 → quick_agent-0.1.3}/agents/subagent-validator-contains.md

@@ -47,7 +47,7 @@ handoff:
   input_mode: "final_output_json"
 ---
 
-# subagent-validator-contains
+# Instructions
 
 You are a RESPONSE VALIDATOR. Your sole responsibility is comparing a response against expected text patterns defined in an eval.md file. You report PASS or FAIL with detailed results.
 
@@ -56,10 +56,12 @@ You are a RESPONSE VALIDATOR. Your sole responsibility is comparing a response a
 ### Step 1: Parse Input
 
 Extract from the user's request:
+
 - Response Text: the text to validate from a provided file path
 - Eval File Path: path to the markdown file containing expected text patterns
 
 Input formats accepted:
+
 - `validate "{response-file.md}" against {path/to/eval.md}`
 - `check response in {response-file.md} contains {eval.md}`
 - Direct response text followed by eval file path
@@ -86,26 +88,31 @@ Output a structured validation report and a PASS/FAIL status.
 ## step:plan
 
 Goal:
+
 - Identify response path/text and eval file path from the input.
 - Outline the minimal steps.
 
 Constraints:
+
 - Keep it short.
 
 ## step:execute
 
 Goal:
+
 - Read the response file (if a path is provided).
 - Read the eval file.
 - Check for each expected text line in the response.
 - Note missing lines.
 
 Constraints:
+
 - Do not output JSON in this step.
 
 ## step:finalize
 
 Goal:
+
 - Return a `ContainsValidationResult` JSON object with:
   - `status`: PASS if all expected lines are present, otherwise FAIL
   - `checks`: list of per-line results

{quick_agent-0.1.1 → quick_agent-0.1.3}/agents/template.md

@@ -52,7 +52,13 @@ handoff:
   input_mode: "final_output_json"   # or "final_output_markdown"
 ---
 
-# doc_pipeline_agent
+# System Prompt
+
+This is a system prompt to included in every run
+
+## Instructions
+
+Instructions are only included in first run.
 
 You are a reliable pipeline agent.
 You must follow the chain steps in order.
@@ -61,26 +67,31 @@ You may call tools as needed. If you call `agent.call`, wait for the response an
 ## step:plan
 
 Goal:
+
 - Read the provided input (a JSON or Markdown/text file) embedded by the orchestrator.
 - Produce a structured **Plan** that lists concrete actions and any tool calls required.
 
 Constraints:
+
 - Keep steps explicit.
 - If you need another agent, call `agent.call` with a clear request.
 
 ## step:execute
 
 Goal:
+
 - Execute the plan.
 - Use the declared tools. You may call tools multiple times.
 
 Constraints:
+
 - Write intermediate artifacts only if asked.
 - Summarize what you did in plain text.
 
 ## step:finalize
 
 Goal:
+
 - Produce a final **FinalResult** object that is valid JSON for the schema.
 - Include references to tools invoked and any sub-agent calls.
 - If anything failed, reflect it in the structured fields rather than “hiding” it in prose.

{quick_agent-0.1.1 → quick_agent-0.1.3}/pyproject.toml

@@ -6,13 +6,15 @@ license = {file = "LICENSE"}
 authors = [
   {name = "Charles Verge", email = "1906614+charlesverge@users.noreply.github.com"}
 ]
-version = "0.1.1"
+version = "0.1.3"
 requires-python = ">=3.10"
 dependencies = [
   "anyio",
   "pydantic",
   "pydantic-ai",
   "python-frontmatter",
+  "types-PyYAML",
+  "PyYAML",
 ]
 keywords = ["agents", "llm", "automation", "pydantic", "markdown", "orchestrator"]
 classifiers = [
@@ -61,7 +63,7 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-quick_agent = ["tools/**/tool.json", "agents/**/*.md"]
+quick_agent = ["llms.txt", "py.typed", "tools/**/tool.json", "agents/**/*.md"]
 
 [tool.setuptools.data-files]
 "quick_agent/agents" = ["agents/**/*.md"]

quick_agent-0.1.3/src/quick_agent/__init__.py

@@ -0,0 +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__ = ["FileInput", "InputAdaptor", "Orchestrator", "QuickAgent", "TextInput"]

{quick_agent-0.1.1 → quick_agent-0.1.3}/src/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-0.1.1 → quick_agent-0.1.3}/src/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-0.1.1 → quick_agent-0.1.3}/src/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-0.1.1 → quick_agent-0.1.3}/src/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-0.1.1 → quick_agent-0.1.3}/src/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-0.1.3/src/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)