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

quick_agent/agent_registry.py

@@ -2,38 +2,18 @@
 
 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:
@@ -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/llms.txt

@@ -3,7 +3,7 @@
 **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.
+- 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`).

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

quick_agent/prompting.py

@@ -2,27 +2,45 @@
 
 from __future__ import annotations
 
-import json
 from typing import Any, Mapping
 
+import yaml
+
 from quick_agent.models.run_input import RunInput
 
 
-def make_user_prompt(step_prompt: str, run_input: RunInput, state: Mapping[str, Any]) -> str:
+def make_user_prompt(run_input: RunInput, state: Mapping[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}
-"""
+    is_inline = run_input.source_path == "inline_input.txt"
+    steps_state = state.get("steps") if isinstance(state, Mapping) else None
+    has_state = bool(steps_state)
+    include_input_header = not (is_inline and not has_state)
+
+    lines: list[str] = []
+    if not is_inline:
+        lines.extend(
+            [
+                "# Task Input",
+                f"source_path: {run_input.source_path}",
+                f"kind: {run_input.kind}",
+                "",
+            ]
+        )
+
+    if include_input_header:
+        lines.append("## Input Content")
+    lines.append(run_input.text)
+
+    if has_state:
+        state_yaml = yaml.safe_dump(
+            steps_state,
+            allow_unicode=False,
+            default_flow_style=False,
+            sort_keys=True,
+        ).rstrip()
+        lines.extend(["", "## Chain State (YAML)", state_yaml])
+
+    return "\n".join(lines).rstrip() + "\n"

quick_agent/quick_agent.py

@@ -53,9 +53,9 @@ class QuickAgent:
         self._agent_id: str = agent_id
         self._input_data: InputAdaptor | Path = input_data
         self._extra_tools: list[str] | None = extra_tools
-        self._write_output_file: bool = write_output
-
         self.loaded: LoadedAgentFile = self._registry.get(self._agent_id)
+        output_file = self.loaded.spec.output.file
+        self._write_output_file: bool = write_output and bool(output_file)
         safe_dir = self.loaded.spec.safe_dir
         if safe_dir is not None and Path(safe_dir).is_absolute():
             raise ValueError("safe_dir must be a relative path.")
@@ -66,22 +66,23 @@ class QuickAgent:
             input_adaptor = FileInput(self._input_data, self.permissions)
         self.run_input: RunInput = input_adaptor.load()
 
-        self.tool_ids: list[str] = list(
-            dict.fromkeys((self.loaded.spec.tools or []) + (self._extra_tools or []))
-        )
-        self.toolset: FunctionToolset[Any] = self._tools.build_toolset(self.tool_ids, self.permissions)
+        self.tool_ids: list[str] = self._build_tool_ids()
+        self.toolset: FunctionToolset[Any] | None = self._build_toolset()
 
         self.model: OpenAIChatModel = build_model(self.loaded.spec.model)
         self.model_settings_json: ModelSettings | None = self._build_model_settings(self.loaded.spec.model)
         self.state: ChainState = self._init_state()
 
     async def run(self) -> BaseModel | str:
-        self._tools.maybe_inject_agent_call(
-            self.tool_ids,
-            self.toolset,
-            self.run_input.source_path,
-            self._run_nested_agent,
-        )
+        if self.has_tools():
+            if self.toolset is None:
+                raise ValueError("Toolset is missing while tools are enabled.")
+            self._tools.maybe_inject_agent_call(
+                self.tool_ids,
+                self.toolset,
+                self.run_input.source_path,
+                self._run_nested_agent,
+            )
 
         final_output = await self._run_chain()
 
@@ -162,34 +163,59 @@ class QuickAgent:
 
         raise NotImplementedError(f"Unknown step kind: {step.kind}")
 
-    def _build_user_prompt(
-        self,
-        *,
-        step: ChainStepSpec,
-    ) -> str:
-        if step.prompt_section not in self.loaded.step_prompts:
-            raise KeyError(f"Missing step section {step.prompt_section!r} in agent.md body.")
+    def _build_user_prompt(self) -> str:
+        return make_user_prompt(self.run_input, self.state)
 
-        step_prompt = self.loaded.step_prompts[step.prompt_section]
-        return make_user_prompt(step_prompt, self.run_input, self.state)
+    def _build_step_instructions(self, step_prompt: str) -> str:
+        if not self.loaded.instructions:
+            return step_prompt
+        return f"{self.loaded.instructions}{step_prompt}"
+
+    def _build_single_shot_prompt(self) -> str:
+        return make_user_prompt(self.run_input, self.state)
+
+    def _normalize_agent_text(self, text: str) -> str | None:
+        if text:
+            return text
+        return None
+
+    def _normalize_system_prompt(self, text: str) -> str | list[str]:
+        if text:
+            return text
+        return []
 
     async def _run_text_step(
         self,
         *,
         step: ChainStepSpec,
     ) -> tuple[StepOutput, BaseModel | str]:
-        user_prompt = self._build_user_prompt(
-            step=step,
-        )
+        user_prompt = self._build_user_prompt()
+        step_prompt = self.loaded.step_prompts[step.prompt_section]
+        step_instructions = self._build_step_instructions(step_prompt)
+        toolsets = self._toolsets_for_run()
         agent = Agent(
             self.model,
-            instructions=self.loaded.body,
-            toolsets=[self.toolset],
+            instructions=step_instructions,
+            system_prompt=self._normalize_system_prompt(self.loaded.system_prompt),
+            toolsets=toolsets,
             output_type=str,
         )
         result = await agent.run(user_prompt)
         return result.output, result.output
 
+    async def _run_single_shot(self) -> BaseModel | str:
+        user_prompt = self._build_single_shot_prompt()
+        toolsets = self._toolsets_for_run()
+        agent = Agent(
+            self.model,
+            instructions=self._normalize_agent_text(self.loaded.instructions),
+            system_prompt=self._normalize_system_prompt(self.loaded.system_prompt),
+            toolsets=toolsets,
+            output_type=str,
+        )
+        result = await agent.run(user_prompt)
+        return result.output
+
     async def _run_structured_step(
         self,
         *,
@@ -201,28 +227,37 @@ class QuickAgent:
 
         model_settings = self._build_structured_model_settings(schema_cls=schema_cls)
 
-        user_prompt = self._build_user_prompt(
-            step=step,
-        )
+        user_prompt = self._build_user_prompt()
+        step_prompt = self.loaded.step_prompts[step.prompt_section]
+        step_instructions = self._build_step_instructions(step_prompt)
+        toolsets = self._toolsets_for_run()
         agent = Agent(
             self.model,
-            instructions=self.loaded.body,
-            toolsets=[self.toolset],
-            output_type=str,
+            instructions=step_instructions,
+            system_prompt=self._normalize_system_prompt(self.loaded.system_prompt),
+            toolsets=toolsets,
+            output_type=schema_cls,
             model_settings=model_settings,
         )
         result = await agent.run(user_prompt)
         raw_output = result.output
-        try:
-            parsed = schema_cls.model_validate_json(raw_output)
-        except ValidationError:
-            extracted = extract_first_json_object(raw_output)
-            parsed = schema_cls.model_validate_json(extracted)
+        if isinstance(raw_output, BaseModel):
+            parsed = raw_output
+        elif isinstance(raw_output, dict):
+            parsed = schema_cls.model_validate(raw_output)
+        else:
+            try:
+                parsed = schema_cls.model_validate_json(raw_output)
+            except ValidationError:
+                extracted = extract_first_json_object(raw_output)
+                parsed = schema_cls.model_validate_json(extracted)
         return parsed.model_dump(), parsed
 
     async def _run_chain(
         self,
     ) -> BaseModel | str:
+        if not self.loaded.spec.chain:
+            return await self._run_single_shot()
         final_output: BaseModel | str = ""
         for step in self.loaded.spec.chain:
             step_out, step_final = await self._run_step(
@@ -233,8 +268,34 @@ class QuickAgent:
             final_output = step_final
         return final_output
 
+    def has_tools(self) -> bool:
+        if not self.tool_ids:
+            return False
+        return True
+
+    def _build_tool_ids(self) -> list[str]:
+        if not self.loaded.spec.tools:
+            return []
+        return list(dict.fromkeys((self.loaded.spec.tools or []) + (self._extra_tools or [])))
+
+    def _build_toolset(self) -> FunctionToolset[Any] | None:
+        if not self.has_tools():
+            return None
+        return self._tools.build_toolset(self.tool_ids, self.permissions)
+
+    def _toolsets_for_run(self) -> list[FunctionToolset[Any]]:
+        if not self.has_tools():
+            return []
+        toolset = self.toolset
+        if toolset is None:
+            return []
+        return [toolset]
+
     def _write_final_output(self, final_output: BaseModel | str) -> Path:
-        out_path = Path(self.loaded.spec.output.file)
+        output_file = self.loaded.spec.output.file
+        if not output_file:
+            raise ValueError("Output file is not configured.")
+        out_path = Path(output_file)
         if isinstance(final_output, BaseModel):
             if self.loaded.spec.output.format == "json":
                 write_output(out_path, final_output.model_dump_json(indent=2), self.permissions)

{quick_agent-0.1.2.data → quick_agent-0.1.3.data}/data/quick_agent/agents/business-extract-structured.md

@@ -24,7 +24,7 @@ output:
   file: "out/business_extract_structured.json"
 ---
 
-# Business Extract Structured
+## Instructions
 
 Extract structured details from the input description.
 

{quick_agent-0.1.2.data → quick_agent-0.1.3.data}/data/quick_agent/agents/business-extract.md

@@ -21,7 +21,7 @@ output:
   file: "out/business_extract.md"
 ---
 
-# Business Extract
+## Instructions
 
 Extract structured details from the input description.
 

{quick_agent-0.1.2.data → quick_agent-0.1.3.data}/data/quick_agent/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.2.data → quick_agent-0.1.3.data}/data/quick_agent/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.2.data → quick_agent-0.1.3.data}/data/quick_agent/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.2.data → quick_agent-0.1.3.data}/data/quick_agent/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.2.dist-info → quick_agent-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick-agent
-Version: 0.1.2
+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"
@@ -908,6 +910,7 @@ 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
 
@@ -926,6 +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.