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

quick_agent/orchestrator.py

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

quick_agent/prompting.py

@@ -2,27 +2,45 @@
 
 from __future__ import annotations
 
-import json
-from typing import Any
+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: dict[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/py.typed

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

quick_agent/quick_agent.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
-from typing import Any, Type
+from typing import Any, Type, TypeAlias, TypedDict
 
 from pydantic import BaseModel, ValidationError
 from pydantic_ai import Agent
@@ -16,13 +16,24 @@ from pydantic_ai.toolsets import FunctionToolset
 from quick_agent.agent_registry import AgentRegistry
 from quick_agent.agent_tools import AgentTools
 from quick_agent.directory_permissions import DirectoryPermissions
-from quick_agent.io_utils import load_input, write_output
+from quick_agent.input_adaptors import FileInput, InputAdaptor, TextInput
+from quick_agent.io_utils import write_output
 from quick_agent.json_utils import extract_first_json_object
 from quick_agent.models.loaded_agent_file import LoadedAgentFile
+from quick_agent.models.chain_step_spec import ChainStepSpec
 from quick_agent.models.model_spec import ModelSpec
+from quick_agent.models.run_input import RunInput
 from quick_agent.prompting import make_user_prompt
 from quick_agent.tools_loader import import_symbol
 
+StepOutput: TypeAlias = str | dict[str, Any]
+
+
+class ChainState(TypedDict):
+    agent_id: str
+    steps: dict[str, StepOutput]
+    final_output: StepOutput | None
+
 
 class QuickAgent:
     def __init__(
@@ -32,68 +43,74 @@ class QuickAgent:
         tools: AgentTools,
         directory_permissions: DirectoryPermissions,
         agent_id: str,
-        input_path: Path,
+        input_data: InputAdaptor | Path,
         extra_tools: list[str] | None,
+        write_output: bool = True,
     ) -> None:
-        self._registry = registry
-        self._tools = tools
-        self._directory_permissions = directory_permissions
-        self._agent_id = agent_id
-        self._input_path = input_path
-        self._extra_tools = extra_tools
-
-        self.loaded = self._registry.get(self._agent_id)
+        self._registry: AgentRegistry = registry
+        self._tools: AgentTools = tools
+        self._directory_permissions: DirectoryPermissions = directory_permissions
+        self._agent_id: str = agent_id
+        self._input_data: InputAdaptor | Path = input_data
+        self._extra_tools: list[str] | None = extra_tools
+        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.")
-        self.permissions = self._directory_permissions.scoped(safe_dir)
-        self.run_input = load_input(self._input_path, self.permissions)
+        self.permissions: DirectoryPermissions = self._directory_permissions.scoped(safe_dir)
+        if isinstance(self._input_data, InputAdaptor):
+            input_adaptor = self._input_data
+        else:
+            input_adaptor = FileInput(self._input_data, self.permissions)
+        self.run_input: RunInput = input_adaptor.load()
 
-        self.tool_ids = list(dict.fromkeys((self.loaded.spec.tools or []) + (self._extra_tools or [])))
-        self.toolset = 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 = build_model(self.loaded.spec.model)
-        self.model_settings_json = self._build_model_settings(self.loaded.spec.model)
-        self.state = self._init_state(self._agent_id)
+        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(
-            loaded=self.loaded,
-            model=self.model,
-            model_settings_json=self.model_settings_json,
-            toolset=self.toolset,
-            run_input=self.run_input,
-            state=self.state,
-        )
+        final_output = await self._run_chain()
 
-        out_path = self._write_final_output(self.loaded, final_output, self.permissions)
+        if self._write_output_file:
+            self._write_final_output(final_output)
 
-        await self._handle_handoff(self.loaded, out_path)
+        await self._handle_handoff(final_output)
 
         return final_output
 
-    async def _run_nested_agent(self, agent_id: str, input_path: Path) -> BaseModel | str:
+    async def _run_nested_agent(self, agent_id: str, input_data: InputAdaptor | Path) -> BaseModel | str:
+        nested_write_output = self.loaded.spec.nested_output == "file"
         agent = QuickAgent(
             registry=self._registry,
             tools=self._tools,
             directory_permissions=self._directory_permissions,
             agent_id=agent_id,
-            input_path=input_path,
+            input_data=input_data,
             extra_tools=None,
+            write_output=nested_write_output,
         )
         return await agent.run()
 
-    def _init_state(self, agent_id: str) -> dict[str, Any]:
+    def _init_state(self) -> ChainState:
         return {
-            "agent_id": agent_id,
+            "agent_id": self._agent_id,
             "steps": {},
+            "final_output": None,
         }
 
     def _build_model_settings(self, model_spec: ModelSpec) -> ModelSettings | None:
@@ -103,21 +120,15 @@ class QuickAgent:
                 return {"extra_body": {"format": "json"}}
         return None
 
-    def _build_structured_model_settings(
-        self,
-        *,
-        model: OpenAIChatModel,
-        model_settings_json: ModelSettings | None,
-        schema_cls: Type[BaseModel],
-    ) -> ModelSettings | None:
-        model_settings: ModelSettings | None = model_settings_json
-        provider = getattr(model, "provider", None)
+    def _build_structured_model_settings(self, *, schema_cls: Type[BaseModel]) -> ModelSettings | None:
+        model_settings: ModelSettings | None = self.model_settings_json
+        provider = getattr(self.model, "provider", None)
         base_url = getattr(provider, "base_url", None)
         if base_url == "https://api.openai.com/v1":
-            if model_settings_json is None:
+            if self.model_settings_json is None:
                 model_settings_dict: ModelSettings = {}
             else:
-                model_settings_dict = model_settings_json
+                model_settings_dict = self.model_settings_json
             extra_body_obj = model_settings_dict.get("extra_body")
             extra_body: dict[str, Any] = {}
             if isinstance(extra_body_obj, dict):
@@ -138,164 +149,169 @@ class QuickAgent:
     async def _run_step(
         self,
         *,
-        step: Any,
-        loaded: LoadedAgentFile,
-        model: OpenAIChatModel,
-        model_settings_json: ModelSettings | None,
-        toolset: FunctionToolset[Any],
-        run_input: Any,
-        state: dict[str, Any],
-    ) -> tuple[Any, BaseModel | str]:
+        step: ChainStepSpec,
+    ) -> tuple[StepOutput, BaseModel | str]:
         if step.kind == "text":
             return await self._run_text_step(
                 step=step,
-                loaded=loaded,
-                model=model,
-                toolset=toolset,
-                run_input=run_input,
-                state=state,
             )
 
         if step.kind == "structured":
             return await self._run_structured_step(
                 step=step,
-                loaded=loaded,
-                model=model,
-                model_settings_json=model_settings_json,
-                toolset=toolset,
-                run_input=run_input,
-                state=state,
             )
 
         raise NotImplementedError(f"Unknown step kind: {step.kind}")
 
-    def _build_user_prompt(
-        self,
-        *,
-        step: Any,
-        loaded: LoadedAgentFile,
-        run_input: Any,
-        state: dict[str, Any],
-    ) -> str:
-        if step.prompt_section not in 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)
+
+    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
 
-        step_prompt = loaded.step_prompts[step.prompt_section]
-        return make_user_prompt(step_prompt, run_input, state)
+    def _normalize_system_prompt(self, text: str) -> str | list[str]:
+        if text:
+            return text
+        return []
 
     async def _run_text_step(
         self,
         *,
-        step: Any,
-        loaded: LoadedAgentFile,
-        model: OpenAIChatModel,
-        toolset: FunctionToolset[Any],
-        run_input: Any,
-        state: dict[str, Any],
-    ) -> tuple[Any, BaseModel | str]:
-        user_prompt = self._build_user_prompt(
-            step=step,
-            loaded=loaded,
-            run_input=run_input,
-            state=state,
-        )
+        step: ChainStepSpec,
+    ) -> tuple[StepOutput, BaseModel | str]:
+        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(
-            model,
-            instructions=loaded.body,
-            toolsets=[toolset],
+            self.model,
+            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,
         *,
-        step: Any,
-        loaded: LoadedAgentFile,
-        model: OpenAIChatModel,
-        model_settings_json: ModelSettings | None,
-        toolset: FunctionToolset[Any],
-        run_input: Any,
-        state: dict[str, Any],
-    ) -> tuple[Any, BaseModel | str]:
+        step: ChainStepSpec,
+    ) -> tuple[StepOutput, BaseModel | str]:
         if not step.output_schema:
             raise ValueError(f"Step {step.id} is structured but missing output_schema.")
-        schema_cls = resolve_schema(loaded, step.output_schema)
+        schema_cls = resolve_schema(self.loaded, step.output_schema)
 
-        model_settings = self._build_structured_model_settings(
-            model=model,
-            model_settings_json=model_settings_json,
-            schema_cls=schema_cls,
-        )
+        model_settings = self._build_structured_model_settings(schema_cls=schema_cls)
 
-        user_prompt = self._build_user_prompt(
-            step=step,
-            loaded=loaded,
-            run_input=run_input,
-            state=state,
-        )
+        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(
-            model,
-            instructions=loaded.body,
-            toolsets=[toolset],
-            output_type=str,
+            self.model,
+            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,
-        *,
-        loaded: LoadedAgentFile,
-        model: OpenAIChatModel,
-        model_settings_json: ModelSettings | None,
-        toolset: FunctionToolset[Any],
-        run_input: Any,
-        state: dict[str, Any],
     ) -> BaseModel | str:
+        if not self.loaded.spec.chain:
+            return await self._run_single_shot()
         final_output: BaseModel | str = ""
-        for step in loaded.spec.chain:
+        for step in self.loaded.spec.chain:
             step_out, step_final = await self._run_step(
                 step=step,
-                loaded=loaded,
-                model=model,
-                model_settings_json=model_settings_json,
-                toolset=toolset,
-                run_input=run_input,
-                state=state,
             )
-            state["steps"][step.id] = step_out
+            self.state["steps"][step.id] = step_out
+            self.state["final_output"] = step_out
             final_output = step_final
         return final_output
 
-    def _write_final_output(
-        self,
-        loaded: LoadedAgentFile,
-        final_output: BaseModel | str,
-        permissions: DirectoryPermissions,
-    ) -> Path:
-        out_path = Path(loaded.spec.output.file)
+    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:
+        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 loaded.spec.output.format == "json":
-                write_output(out_path, final_output.model_dump_json(indent=2), permissions)
+            if self.loaded.spec.output.format == "json":
+                write_output(out_path, final_output.model_dump_json(indent=2), self.permissions)
             else:
-                write_output(out_path, final_output.model_dump_json(indent=2), permissions)
+                write_output(out_path, final_output.model_dump_json(indent=2), self.permissions)
         else:
-            write_output(out_path, str(final_output), permissions)
+            write_output(out_path, str(final_output), self.permissions)
         return out_path
 
-    async def _handle_handoff(self, loaded: LoadedAgentFile, out_path: Path) -> None:
-        if loaded.spec.handoff.enabled and loaded.spec.handoff.agent_id:
-            # For a more robust version, generate an intermediate file for handoff input.
-            await self._run_nested_agent(loaded.spec.handoff.agent_id, out_path)
+    async def _handle_handoff(self, final_output: BaseModel | str) -> None:
+        if self.loaded.spec.handoff.enabled and self.loaded.spec.handoff.agent_id:
+            if isinstance(final_output, BaseModel):
+                payload = final_output.model_dump_json(indent=2)
+            else:
+                payload = str(final_output)
+            await self._run_nested_agent(self.loaded.spec.handoff.agent_id, TextInput(payload))
 
 
 def resolve_schema(loaded: LoadedAgentFile, schema_name: str) -> Type[BaseModel]:

quick_agent/schemas/outputs.py

@@ -26,6 +26,12 @@ class ValidationResult(BaseModel):
     summary: str | None = None
 
 
+class BusinessSummary(BaseModel):
+    company_name: str
+    location: str
+    summary: str
+
+
 class EvalRowResult(BaseModel):
     index: int = 0
     agent: str

quick_agent-0.1.3.data/data/quick_agent/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.data/data/quick_agent/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.