quick-agent 0.1.1__py3-none-any.whl

quick_agent/quick_agent.py

@@ -0,0 +1,313 @@
+"""Agent execution logic."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Type
+
+from pydantic import BaseModel, ValidationError
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.settings import ModelSettings
+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.json_utils import extract_first_json_object
+from quick_agent.models.loaded_agent_file import LoadedAgentFile
+from quick_agent.models.model_spec import ModelSpec
+from quick_agent.prompting import make_user_prompt
+from quick_agent.tools_loader import import_symbol
+
+
+class QuickAgent:
+    def __init__(
+        self,
+        *,
+        registry: AgentRegistry,
+        tools: AgentTools,
+        directory_permissions: DirectoryPermissions,
+        agent_id: str,
+        input_path: Path,
+        extra_tools: list[str] | None,
+    ) -> 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)
+        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.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.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)
+
+    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,
+        )
+
+        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,
+        )
+
+        out_path = self._write_final_output(self.loaded, final_output, self.permissions)
+
+        await self._handle_handoff(self.loaded, out_path)
+
+        return final_output
+
+    async def _run_nested_agent(self, agent_id: str, input_path: Path) -> BaseModel | str:
+        agent = QuickAgent(
+            registry=self._registry,
+            tools=self._tools,
+            directory_permissions=self._directory_permissions,
+            agent_id=agent_id,
+            input_path=input_path,
+            extra_tools=None,
+        )
+        return await agent.run()
+
+    def _init_state(self, agent_id: str) -> dict[str, Any]:
+        return {
+            "agent_id": agent_id,
+            "steps": {},
+        }
+
+    def _build_model_settings(self, model_spec: ModelSpec) -> ModelSettings | None:
+        if model_spec.provider == "openai-compatible":
+            # Ollama OpenAI-compatible API uses "format": "json" to force JSON output.
+            if model_spec.base_url != "https://api.openai.com/v1":
+                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)
+        base_url = getattr(provider, "base_url", None)
+        if base_url == "https://api.openai.com/v1":
+            if model_settings_json is None:
+                model_settings_dict: ModelSettings = {}
+            else:
+                model_settings_dict = model_settings_json
+            extra_body_obj = model_settings_dict.get("extra_body")
+            extra_body: dict[str, Any] = {}
+            if isinstance(extra_body_obj, dict):
+                extra_body = dict(extra_body_obj)
+            if "response_format" not in extra_body:
+                extra_body["response_format"] = {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": schema_cls.__name__,
+                        "schema": schema_cls.model_json_schema(),
+                        "strict": True,
+                    },
+                }
+            model_settings_dict["extra_body"] = extra_body
+            model_settings = model_settings_dict
+        return model_settings
+
+    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]:
+        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.")
+
+        step_prompt = loaded.step_prompts[step.prompt_section]
+        return make_user_prompt(step_prompt, run_input, state)
+
+    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,
+        )
+        agent = Agent(
+            model,
+            instructions=loaded.body,
+            toolsets=[toolset],
+            output_type=str,
+        )
+        result = await agent.run(user_prompt)
+        return result.output, 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]:
+        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)
+
+        model_settings = self._build_structured_model_settings(
+            model=model,
+            model_settings_json=model_settings_json,
+            schema_cls=schema_cls,
+        )
+
+        user_prompt = self._build_user_prompt(
+            step=step,
+            loaded=loaded,
+            run_input=run_input,
+            state=state,
+        )
+        agent = Agent(
+            model,
+            instructions=loaded.body,
+            toolsets=[toolset],
+            output_type=str,
+            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)
+        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:
+        final_output: BaseModel | str = ""
+        for step in 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
+            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)
+        if isinstance(final_output, BaseModel):
+            if loaded.spec.output.format == "json":
+                write_output(out_path, final_output.model_dump_json(indent=2), permissions)
+            else:
+                write_output(out_path, final_output.model_dump_json(indent=2), permissions)
+        else:
+            write_output(out_path, str(final_output), 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)
+
+
+def resolve_schema(loaded: LoadedAgentFile, schema_name: str) -> Type[BaseModel]:
+    if schema_name not in loaded.spec.schemas:
+        raise KeyError(f"Schema {schema_name!r} not registered in agent.md schemas.")
+    cls = import_symbol(loaded.spec.schemas[schema_name])
+    if not isinstance(cls, type) or not issubclass(cls, BaseModel):
+        raise TypeError(f"Schema {schema_name!r} must be a Pydantic BaseModel subclass.")
+    return cls
+
+
+def build_model(model_spec: ModelSpec) -> OpenAIChatModel:
+    api_key = os.environ.get(model_spec.api_key_env, "noop")
+    provider = OpenAIProvider(base_url=model_spec.base_url, api_key=api_key)
+    return OpenAIChatModel(model_spec.model_name, provider=provider)

quick_agent/schemas/outputs.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, AliasChoices
+
+
+class Plan(BaseModel):
+    # LLMs sometimes emit structured steps; allow both strings and dicts.
+    steps: list[str | dict[str, Any]] = Field(default_factory=list)
+    tool_calls: list[str | dict[str, Any]] = Field(default_factory=list)
+
+
+class ValidationIssue(BaseModel):
+    field: str
+    reason: str
+
+
+class ValidationResult(BaseModel):
+    valid: bool
+    function_name: str | None = None
+    parameters_count: int | None = None
+    return_type: str | None = None
+    target_path: str | None = None
+    issues: list[ValidationIssue] = Field(default_factory=list)
+    summary: str | None = None
+
+
+class EvalRowResult(BaseModel):
+    index: int = 0
+    agent: str
+    command_file: str
+    result: str = Field(default="", validation_alias=AliasChoices("result", "results"))  # "PASS" or "FAIL"
+    note: str | None = None
+
+
+class EvalListResult(BaseModel):
+    total: int
+    passed: int
+    failed: int
+    results_path: str
+    rows: list[EvalRowResult] = Field(default_factory=list)
+
+
+class ContainsCheck(BaseModel):
+    text: str
+    found: bool
+
+
+class ContainsValidationResult(BaseModel):
+    status: str  # "PASS" or "FAIL"
+    checks: list[ContainsCheck] = Field(default_factory=list)
+    missing: list[str] = Field(default_factory=list)
+    eval_path: str | None = None
+    response_path: str | None = None

quick_agent/tools/filesystem/adapter.py

@@ -0,0 +1,26 @@
+"""Filesystem tool adapter with directory permissions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from quick_agent.directory_permissions import DirectoryPermissions
+
+
+class FilesystemToolAdapter:
+    def __init__(self, permissions: DirectoryPermissions) -> None:
+        self._permissions = permissions
+
+    def read_text(self, path: str) -> str:
+        if not self._permissions.can_read(Path(path)):
+            raise PermissionError(f"Read access denied for {path}.")
+        safe_path = self._permissions.resolve(Path(path), for_write=False)
+        return safe_path.read_text(encoding="utf-8")
+
+    def write_text(self, path: str, content: str) -> str:
+        if not self._permissions.can_write(Path(path)):
+            raise PermissionError(f"Write access denied for {path}.")
+        safe_path = self._permissions.resolve(Path(path), for_write=True)
+        safe_path.parent.mkdir(parents=True, exist_ok=True)
+        safe_path.write_text(content, encoding="utf-8")
+        return str(safe_path)

quick_agent/tools/filesystem/read_text.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from quick_agent.directory_permissions import DirectoryPermissions
+
+
+def read_text(
+    path: str,
+    permissions: DirectoryPermissions,
+) -> str:
+    """Read UTF-8 text from a file path."""
+    if not permissions.can_read(Path(path)):
+        raise PermissionError(f"Read access denied for {path}.")
+    safe_path = permissions.resolve(Path(path), for_write=False)
+    return safe_path.read_text(encoding="utf-8")

quick_agent/tools/filesystem/write_text.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from quick_agent.directory_permissions import DirectoryPermissions
+
+
+def write_text(
+    path: str,
+    content: str,
+    permissions: DirectoryPermissions,
+) -> str:
+    """Write UTF-8 text to a file path. Returns the written path."""
+    if not permissions.can_write(Path(path)):
+        raise PermissionError(f"Write access denied for {path}.")
+    out = permissions.resolve(Path(path), for_write=True)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(content, encoding="utf-8")
+    return str(out)

quick_agent/tools/filesystem.read_text/tool.json

@@ -0,0 +1,10 @@
+{
+  "id": "filesystem.read_text",
+  "name": "filesystem.read_text",
+  "description": "Read a UTF-8 text file from disk.",
+  "impl": {
+    "kind": "python",
+    "module": "quick_agent.tools.filesystem.read_text",
+    "function": "read_text"
+  }
+}

quick_agent/tools/filesystem.write_text/tool.json

@@ -0,0 +1,10 @@
+{
+  "id": "filesystem.write_text",
+  "name": "filesystem.write_text",
+  "description": "Write a UTF-8 text file to disk. Returns the written path.",
+  "impl": {
+    "kind": "python",
+    "module": "quick_agent.tools.filesystem.write_text",
+    "function": "write_text"
+  }
+}

quick_agent/tools_loader.py

@@ -0,0 +1,76 @@
+"""Tool discovery and loading."""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from collections.abc import Callable
+from typing import Any
+
+from pydantic_ai.toolsets import FunctionToolset
+
+from quick_agent.directory_permissions import DirectoryPermissions
+from quick_agent.models.tool_json import ToolJson
+from quick_agent.tools.filesystem.adapter import FilesystemToolAdapter
+
+
+def import_symbol(path: str) -> Any:
+    """
+    Imports a symbol given "package.module:SymbolName".
+    """
+    if ":" not in path:
+        raise ValueError(f"Expected import path 'module:Symbol', got {path!r}")
+    mod, sym = path.split(":", 1)
+    module = importlib.import_module(mod)
+    return getattr(module, sym)
+
+
+def _discover_tool_index(tool_roots: list[Path]) -> dict[str, Path]:
+    index: dict[str, Path] = {}
+    for root in tool_roots:
+        if not root.exists():
+            continue
+        for tool_json_path in root.rglob("tool.json"):
+            tool_obj = ToolJson.model_validate_json(tool_json_path.read_text(encoding="utf-8"))
+            if tool_obj.id in index:
+                continue
+            index[tool_obj.id] = tool_json_path
+    return index
+
+
+def load_tools(
+    tool_roots: list[Path],
+    tool_ids: list[str],
+    permissions: DirectoryPermissions,
+) -> FunctionToolset[Any]:
+    """
+    Minimal approach: load local python functions and register them into a FunctionToolset.
+    """
+    toolset = FunctionToolset()
+
+    tool_index = _discover_tool_index(tool_roots)
+    fs_adapter = FilesystemToolAdapter(permissions)
+
+    for tool_id in tool_ids:
+        tool_json_path = tool_index.get(tool_id)
+        if tool_json_path is None:
+            raise FileNotFoundError(f"Missing tool.json for tool {tool_id} in roots: {tool_roots}")
+
+        tool_obj = ToolJson.model_validate_json(tool_json_path.read_text(encoding="utf-8"))
+        if tool_obj.impl.kind != "python":
+            raise NotImplementedError("Skeleton supports python tools only. Add MCP support next.")
+
+        func: Callable[..., Any]
+        if tool_id == "filesystem.read_text":
+            func = fs_adapter.read_text
+        elif tool_id == "filesystem.write_text":
+            func = fs_adapter.write_text
+        else:
+            func = import_symbol(f"{tool_obj.impl.module}:{tool_obj.impl.function}")
+
+        # Register function as a tool.
+        # The FunctionToolset will derive schema from type hints / docstring.
+        # You can enforce consistency with tool.json by adding checks here.
+        toolset.add_function(func=func, name=tool_obj.name, description=tool_obj.description)
+
+    return toolset

quick_agent-0.1.1.data/data/quick_agent/agents/function-spec-validator.md

@@ -0,0 +1,109 @@
+---
+# Agent identity
+name: "function_spec_validator"
+description: "Validates function specifications meet required standards before creation."
+
+# Model configuration: OpenAI-compatible endpoint (e.g., SGLang server)
+model:
+  provider: "openai-compatible"
+  base_url: "http://localhost:11434/v1"
+  api_key_env: "OLLAMA_API_KEY"
+  model_name: "gpt-oss:20b"
+  temperature: 0.2
+  max_tokens: 2048
+
+# Tools available to this agent (tool IDs resolved by the orchestrator)
+tools: []
+
+# Schema registry: symbolic names -> import paths
+schemas:
+  Plan: "simple_agent.schemas.outputs:Plan"
+  ValidationResult: "simple_agent.schemas.outputs:ValidationResult"
+
+# Prompt-chaining steps (ordered). Each step references a markdown section below.
+chain:
+  - id: "execute"
+    kind: "text"
+    prompt_section: "step:execute"
+
+  - id: "finalize"
+    kind: "structured"
+    output_schema: "ValidationResult"
+    prompt_section: "step:finalize"
+
+# Output settings
+output:
+  format: "json"
+  file: "out/function_spec_validation.json"
+
+# Optional: handoff to another agent after producing final output
+handoff:
+  enabled: false
+  agent_id: null
+  input_mode: "final_output_json"
+---
+
+# function_spec_validator
+
+You are a validation agent that checks a provided function specification.
+Return a JSON valid result that includes a boolean `valid` field.
+Follow the chain steps in order.
+Do not create comments outside of the structured output.
+
+## Required Fields
+
+1. Function name - must be provided, snake_case format
+2. Parameters with types - each parameter must have a type annotation
+3. Return type - must be specified (use `None` if no return)
+4. Behavior description - must describe what the function does
+5. Target file path - must be a valid Python file path (.py extension)
+
+## Validation Rules
+
+### Function Name
+- Must be non-empty
+- Must use snake_case (lowercase with underscores)
+- Must not start with a number
+- Must not be a Python reserved keyword
+
+### Parameters with Types
+- Each parameter must follow format: `name: Type`
+- Type must be a valid Python type or imported type
+- Optional parameters must specify default values
+- If there are no parameters, the following is accepted: None, an empty list, or no content
+
+### Return Type
+- Must be explicitly stated
+- Use `None` for functions with no return value
+- Complex types must be properly annotated (e.g., `List[str]`, `Dict[str, int]`)
+
+### Behavior Description
+- Minimum 10 characters
+- Must describe the function's purpose
+- Should mention expected inputs and outputs
+
+### Target File Path
+- Must end with `.py`
+- Must be an relative path
+- Project Root level files or within subdirectories are acceptable
+- Project Root level files will not have a leading slash
+
+## step:execute
+
+Goal:
+- Perform the validation checks on all required fields.
+- Summarize findings in plain text and list any missing or invalid fields.
+
+Constraints:
+- Do not output JSON in this step.
+
+## step:finalize
+
+Goal:
+- Return a `ValidationResult` JSON object.
+- The object must include `valid` and should include any issues.
+- If invalid, include the list of issues with `field` and `reason`.
+- No comments on the json code is needed
+- Remove any comments on the json output
+
+Return only the structured object required by the schema (no additional commentary).