moiryx 0.1.0a1__py3-none-any.whl

moiryx/__init__.py

@@ -0,0 +1,6 @@
+"""Public API for Moiryx."""
+
+from moiryx.agent import Agent
+from moiryx.tools import tool
+
+__all__ = ["Agent", "tool"]

moiryx/agent.py

@@ -0,0 +1,200 @@
+"""Eagerly validated public Agent facade."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from moiryx.agent_spec import AgentSpec, load_agent_spec
+from moiryx.config import CapabilityOverrides, RuntimeConfig, load_config
+from moiryx.errors import ConfigurationError, ProviderCapabilityError
+from moiryx.generation import merge_generation_options
+from moiryx.model_registry import ModelRegistry, ResolvedModel
+from moiryx.models import GenerationOptions, ProviderCapabilities, ToolDefinition
+from moiryx.observability import RunObserver
+from moiryx.providers import ProviderAdapter, ProviderRegistry
+from moiryx.redaction import collect_secret_values
+from moiryx.runtime import execute_structured_agent, execute_text_agent
+from moiryx.tools import GLOBAL_TOOL_REGISTRY, build_builtin_tool
+
+
+@dataclass(frozen=True, slots=True)
+class _PreparedAgent:
+    spec: AgentSpec
+    model: ResolvedModel
+    provider: ProviderAdapter
+    tools: tuple[ToolDefinition, ...]
+    capabilities: ProviderCapabilities
+    generation: GenerationOptions
+    runtime: RuntimeConfig
+    observer: RunObserver
+
+
+def _import_tool_modules(module_names: list[str]) -> None:
+    for module_name in module_names:
+        try:
+            import_module(module_name)
+        except Exception as error:
+            raise ConfigurationError(
+                f"Could not import tool module '{module_name}' ({type(error).__name__})"
+            ) from error
+
+
+def _effective_capabilities(
+    adapter: ProviderCapabilities,
+    overrides: CapabilityOverrides,
+) -> ProviderCapabilities:
+    return ProviderCapabilities(
+        tool_calling=(
+            adapter.tool_calling
+            if overrides.tool_calling is None
+            else overrides.tool_calling
+        ),
+        native_structured_output=(
+            adapter.native_structured_output
+            if overrides.native_structured_output is None
+            else overrides.native_structured_output
+        ),
+        parallel_tool_calls=(
+            adapter.parallel_tool_calls
+            if overrides.parallel_tool_calls is None
+            else overrides.parallel_tool_calls
+        ),
+    )
+
+
+def _validate_capabilities(
+    *,
+    spec: AgentSpec,
+    model: ResolvedModel,
+    capabilities: ProviderCapabilities,
+) -> None:
+    if spec.tool_names and not capabilities.tool_calling:
+        raise ProviderCapabilityError(
+            "Agent tools require provider tool-calling capability",
+            agent_name=spec.name,
+            model_alias=model.alias,
+            provider_name=model.provider,
+            model_id=model.model,
+        )
+
+    if spec.output_model is None:
+        return
+    supports_output = capabilities.tool_calling or (
+        not spec.tool_names and capabilities.native_structured_output
+    )
+    if not supports_output:
+        raise ProviderCapabilityError(
+            "Structured output requires tool calling or guaranteed native "
+            "structured output without user tools",
+            agent_name=spec.name,
+            model_alias=model.alias,
+            provider_name=model.provider,
+            model_id=model.model,
+        )
+
+
+class Agent:
+    """An immutable, eagerly resolved agent definition ready for execution."""
+
+    __slots__ = ("_prepared", "_provider_registry")
+
+    def __init__(self, agent_file: str | Path) -> None:
+        config = load_config()
+        _import_tool_modules(config.tool_modules)
+        spec = load_agent_spec(
+            agent_file,
+            default_max_steps=config.runtime.default_max_steps,
+        )
+        model = ModelRegistry(config).resolve(spec.model_alias)
+        tools = tuple(
+            build_builtin_tool(name, config.runtime)
+            or GLOBAL_TOOL_REGISTRY.resolve(name)
+            for name in spec.tool_names
+        )
+
+        provider_registry = ProviderRegistry(config)
+        provider = provider_registry.resolve(model.provider)
+        try:
+            adapter_capabilities = provider.capabilities
+        except (AttributeError, TypeError) as error:
+            raise ConfigurationError(
+                "Provider adapter does not expose valid capabilities",
+                provider_name=model.provider,
+            ) from error
+        if not isinstance(adapter_capabilities, ProviderCapabilities):
+            raise ConfigurationError(
+                "Provider adapter returned invalid capabilities",
+                provider_name=model.provider,
+            )
+        provider_config = config.providers[model.provider]
+        capabilities = _effective_capabilities(
+            adapter_capabilities,
+            provider_config.capabilities,
+        )
+        _validate_capabilities(
+            spec=spec,
+            model=model,
+            capabilities=capabilities,
+        )
+        generation = merge_generation_options(
+            config.runtime.generation,
+            model.generation,
+            spec.generation,
+        )
+
+        self._provider_registry = provider_registry
+        self._prepared = _PreparedAgent(
+            spec=spec,
+            model=model,
+            provider=provider,
+            tools=tools,
+            capabilities=capabilities,
+            generation=generation,
+            runtime=config.runtime,
+            observer=RunObserver(
+                config.logging,
+                secrets=collect_secret_values(config),
+            ),
+        )
+
+    async def __call__(self, prompt: str) -> str | BaseModel:
+        """Execute one isolated run of this eagerly prepared agent."""
+        if self._prepared.spec.output_model is not None:
+            return await execute_structured_agent(
+                provider=self._prepared.provider,
+                spec=self._prepared.spec,
+                model=self._prepared.model,
+                tools=self._prepared.tools,
+                capabilities=self._prepared.capabilities,
+                generation=self._prepared.generation,
+                runtime=self._prepared.runtime,
+                prompt=prompt,
+                observer=self._prepared.observer,
+            )
+        return await execute_text_agent(
+            provider=self._prepared.provider,
+            spec=self._prepared.spec,
+            model=self._prepared.model,
+            tools=self._prepared.tools,
+            generation=self._prepared.generation,
+            runtime=self._prepared.runtime,
+            prompt=prompt,
+            observer=self._prepared.observer,
+        )
+
+    async def aclose(self) -> None:
+        """Release the provider client when this agent is no longer needed."""
+        await self._provider_registry.close()
+
+    async def __aenter__(self) -> Agent:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+
+__all__ = ["Agent"]

moiryx/agent_spec.py

@@ -0,0 +1,154 @@
+"""Parsing and validation of Markdown agent definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Annotated
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from moiryx.errors import AgentDefinitionError, ConfigurationError
+from moiryx.generation import merge_generation_options
+from moiryx.models import GenerationOptions
+from moiryx.output import load_output_model
+
+
+class _AgentFrontmatter(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+    model: Annotated[str, Field(min_length=1)]
+    name: Annotated[str, Field(min_length=1)] | None = None
+    tools: list[str] = Field(default_factory=list)
+    output: Annotated[str, Field(min_length=1)] | None = None
+    max_steps: Annotated[int, Field(gt=0)] | None = None
+    generation: dict[str, object] = Field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentSpec:
+    """Validated, provider-independent definition of an agent."""
+
+    name: str
+    model_alias: str
+    instructions: str
+    tool_names: tuple[str, ...]
+    output_model: type[BaseModel] | None
+    max_steps: int
+    generation: GenerationOptions
+    source_path: Path = field(repr=False, compare=False)
+
+
+def _split_frontmatter(text: str, *, agent_path: Path) -> tuple[object, str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+
+    closing_index = next(
+        (
+            index
+            for index, line in enumerate(lines[1:], start=1)
+            if line.strip() == "---"
+        ),
+        None,
+    )
+    if closing_index is None:
+        raise AgentDefinitionError(
+            f"Agent definition '{agent_path}' has unclosed YAML frontmatter"
+        )
+
+    frontmatter_text = "".join(lines[1:closing_index])
+    body = "".join(lines[closing_index + 1 :])
+    try:
+        frontmatter: object = yaml.safe_load(frontmatter_text)
+    except yaml.YAMLError as error:
+        mark = getattr(error, "problem_mark", None)
+        location = (
+            f" at line {mark.line + 2}, column {mark.column + 1}"
+            if mark is not None
+            else ""
+        )
+        raise AgentDefinitionError(
+            f"Invalid YAML frontmatter in agent '{agent_path}'{location}"
+        ) from error
+
+    return ({} if frontmatter is None else frontmatter), body
+
+
+def _validation_summary(error: ValidationError) -> str:
+    issues: list[str] = []
+    for item in error.errors(
+        include_url=False,
+        include_context=False,
+        include_input=False,
+    ):
+        location = ".".join(str(part) for part in item["loc"])
+        prefix = f"{location}: " if location else ""
+        issues.append(f"{prefix}{item['msg']}")
+    return "; ".join(issues)
+
+
+def load_agent_spec(
+    agent_file: str | Path,
+    *,
+    default_max_steps: int = 20,
+) -> AgentSpec:
+    """Read and fully validate one Markdown agent definition."""
+    agent_path = Path(agent_file)
+    if (
+        isinstance(default_max_steps, bool)
+        or not isinstance(default_max_steps, int)
+        or default_max_steps <= 0
+    ):
+        raise AgentDefinitionError(
+            "default_max_steps must be a positive integer",
+        )
+
+    try:
+        with agent_path.open("r", encoding="utf-8", newline="") as source:
+            text = source.read()
+    except (OSError, UnicodeError) as error:
+        raise AgentDefinitionError(
+            f"Could not read agent definition '{agent_path}': {type(error).__name__}"
+        ) from error
+
+    raw_frontmatter, instructions = _split_frontmatter(text, agent_path=agent_path)
+    if not isinstance(raw_frontmatter, Mapping):
+        raise AgentDefinitionError(
+            f"YAML frontmatter in agent '{agent_path}' must be a mapping"
+        )
+
+    try:
+        frontmatter = _AgentFrontmatter.model_validate(raw_frontmatter)
+    except ValidationError as error:
+        raise AgentDefinitionError(
+            f"Invalid agent definition '{agent_path}': {_validation_summary(error)}"
+        ) from error
+
+    try:
+        generation = merge_generation_options(agent=frontmatter.generation)
+    except ConfigurationError as error:
+        raise AgentDefinitionError(
+            f"Invalid agent definition '{agent_path}': {error.message}"
+        ) from error
+
+    output_model = (
+        load_output_model(frontmatter.output, agent_path=agent_path)
+        if frontmatter.output is not None
+        else None
+    )
+    return AgentSpec(
+        name=frontmatter.name or agent_path.stem,
+        model_alias=frontmatter.model,
+        instructions=instructions,
+        tool_names=tuple(frontmatter.tools),
+        output_model=output_model,
+        max_steps=frontmatter.max_steps or default_max_steps,
+        generation=generation,
+        source_path=agent_path,
+    )
+
+
+__all__ = ["AgentSpec", "load_agent_spec"]