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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick-agent
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -707,13 +707,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 +888,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,
     )
 
@@ -908,6 +909,17 @@ Agents are stored as Markdown files with YAML front matter and step sections:
 
 The orchestrator loads the agent, builds the tools, and executes each step in order, writing the final output to disk.
 
+## 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
 
 See the docs in `docs/`:
@@ -916,3 +928,4 @@ See the docs in `docs/`:
 - [docs/templates.md](docs/templates.md): Agent template format and examples.
 - [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.2}/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,
     )
 
@@ -199,6 +200,17 @@ Agents are stored as Markdown files with YAML front matter and step sections:
 
 The orchestrator loads the agent, builds the tools, and executes each step in order, writing the final output to disk.
 
+## 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
 
 See the docs in `docs/`:
@@ -207,3 +219,4 @@ See the docs in `docs/`:
 - [docs/templates.md](docs/templates.md): Agent template format and examples.
 - [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.2/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"
+---
+
+# Business Extract Structured
+
+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.2/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"
+---
+
+# Business Extract
+
+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.2}/pyproject.toml

@@ -6,7 +6,7 @@ license = {file = "LICENSE"}
 authors = [
   {name = "Charles Verge", email = "1906614+charlesverge@users.noreply.github.com"}
 ]
-version = "0.1.1"
+version = "0.1.2"
 requires-python = ">=3.10"
 dependencies = [
   "anyio",
@@ -61,7 +61,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.2/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.2}/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.2}/src/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-0.1.1 → quick_agent-0.1.2}/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.2}/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.2}/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.2/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)

quick_agent-0.1.2/src/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-0.1.1 → quick_agent-0.1.2}/src/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