loopengt 0.1.0__py3-none-any.whl

loopengt/core/models/agent.py

@@ -0,0 +1,126 @@
+"""Agent role and capability definitions for loop participants."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AgentCapability(StrEnum):
+    """Standard capabilities an agent may declare."""
+
+    CODE_GENERATION = "code_generation"
+    CODE_REVIEW = "code_review"
+    PLANNING = "planning"
+    RESEARCH = "research"
+    TESTING = "testing"
+    EVALUATION = "evaluation"
+    SUMMARIZATION = "summarization"
+    TOOL_USE = "tool_use"
+    DECISION_MAKING = "decision_making"
+    FILE_OPERATIONS = "file_operations"
+    WEB_SEARCH = "web_search"
+    CUSTOM = "custom"
+
+
+class RetryConfig(BaseModel):
+    """Retry configuration for an individual agent."""
+
+    model_config = ConfigDict(frozen=True)
+
+    max_retries: int = Field(default=3, ge=0, description="Maximum retry attempts")
+    backoff_seconds: float = Field(
+        default=1.0, gt=0, description="Initial backoff duration in seconds"
+    )
+    backoff_multiplier: float = Field(
+        default=2.0, ge=1.0, description="Backoff multiplier per retry"
+    )
+
+
+class AgentConfig(BaseModel):
+    """Configuration block for agent-specific settings.
+
+    Holds provider, model, temperature, and arbitrary provider-specific
+    parameters that do not belong in the role definition itself.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    provider: str = Field(
+        default="openai",
+        description="LLM provider identifier (openai, anthropic, ollama, …)",
+    )
+    model: str = Field(
+        default="gpt-4o",
+        description="Model name within the provider",
+    )
+    temperature: float = Field(
+        default=0.7, ge=0.0, le=2.0, description="Sampling temperature"
+    )
+    max_tokens: int | None = Field(
+        default=None, ge=1, description="Max tokens to generate"
+    )
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary provider-specific parameters",
+    )
+
+
+class AgentRole(BaseModel):
+    """Defines a single agent participant in a loop.
+
+    Each agent has a unique name, a set of declared capabilities, optional
+    input/output schemas, timeout, retry, and provider configuration.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Unique agent identifier"
+    )
+    description: str = Field(
+        default="", max_length=2048, description="Human-readable role description"
+    )
+    system_prompt: str = Field(
+        default="",
+        description="System prompt that defines this agent's persona and behaviour",
+    )
+    capabilities: list[AgentCapability] = Field(
+        default_factory=list,
+        description="Declared capabilities of this agent",
+    )
+    input_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON Schema for the data this agent receives",
+    )
+    output_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON Schema for the data this agent produces",
+    )
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Names of tools this agent is allowed to use",
+    )
+    timeout_seconds: float = Field(
+        default=300.0,
+        gt=0,
+        description="Maximum execution time for a single invocation",
+    )
+    retry: RetryConfig = Field(
+        default_factory=RetryConfig,
+        description="Retry behaviour on failure",
+    )
+    config: AgentConfig = Field(
+        default_factory=AgentConfig,
+        description="LLM provider and model configuration",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary key-value metadata",
+    )
+
+    def has_capability(self, capability: AgentCapability) -> bool:
+        """Check whether this agent declares the given capability."""
+        return capability in self.capabilities

loopengt/core/models/loop_spec.py

@@ -0,0 +1,251 @@
+"""Loop specification models — the declarative blueprint for a loop."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from loopengt.core.models.agent import AgentRole
+from loopengt.core.models.policy import Policy
+from loopengt.core.models.tool import ToolSpec
+
+
+class LoopPattern(StrEnum):
+    """Supported orchestration patterns."""
+
+    SEQUENTIAL = "sequential"
+    SUPERVISOR_WORKER = "supervisor_worker"
+    PARALLEL_FAN_OUT = "parallel_fan_out"
+    HANDOFF = "handoff"
+    EVALUATOR_OPTIMIZER = "evaluator_optimizer"
+    CUSTOM = "custom"
+
+
+class StopConditionType(StrEnum):
+    """How a stop condition is evaluated."""
+
+    MAX_TURNS = "max_turns"
+    GOAL_MET = "goal_met"
+    QUALITY_THRESHOLD = "quality_threshold"
+    TIMEOUT = "timeout"
+    MANUAL = "manual"
+    CUSTOM = "custom"
+
+
+class StopCondition(BaseModel):
+    """A condition under which the loop should terminate."""
+
+    model_config = ConfigDict(frozen=True)
+
+    condition_type: StopConditionType = Field(
+        ..., description="Category of stop condition"
+    )
+    value: Any = Field(
+        default=None,
+        description=(
+            "Threshold or expression.  Meaning depends on condition_type: "
+            "int for max_turns, float for quality_threshold, str expression "
+            "for goal_met / custom."
+        ),
+    )
+    description: str = Field(
+        default="", description="Human-readable explanation"
+    )
+
+
+class OutputSchema(BaseModel):
+    """Schema describing the expected loop output."""
+
+    model_config = ConfigDict(frozen=True)
+
+    schema_def: dict[str, Any] = Field(
+        default_factory=dict,
+        description="JSON Schema for the loop's final output",
+    )
+    required_fields: list[str] = Field(
+        default_factory=list,
+        description="Fields that must be present in the output",
+    )
+    description: str = Field(
+        default="", description="Human-readable output description"
+    )
+
+
+class StepDependency(BaseModel):
+    """Declares a dependency between steps."""
+
+    model_config = ConfigDict(frozen=True)
+
+    step_name: str = Field(
+        ..., description="Name of the step that must complete first"
+    )
+    condition: str | None = Field(
+        default=None,
+        description="Optional condition on the dependency step's result",
+    )
+
+
+class StepSpec(BaseModel):
+    """Specification for a single step within a loop.
+
+    Steps bind an agent to a task with optional tool access, dependencies,
+    and verification gates.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Unique step identifier"
+    )
+    description: str = Field(
+        default="", max_length=2048, description="What this step accomplishes"
+    )
+    agent: str = Field(
+        ..., description="Name of the agent responsible for this step"
+    )
+    prompt_template: str = Field(
+        default="",
+        description=(
+            "Prompt template with ``{variable}`` placeholders resolved "
+            "from the loop context at execution time"
+        ),
+    )
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Tool names available during this step",
+    )
+    dependencies: list[StepDependency] = Field(
+        default_factory=list,
+        description="Steps that must complete before this one starts",
+    )
+    verification_gates: list[str] = Field(
+        default_factory=list,
+        description="Names of verification gates to evaluate after this step",
+    )
+    timeout_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description="Per-step timeout override (falls back to policy default)",
+    )
+    allow_retry: bool = Field(
+        default=True, description="Whether this step can be retried on failure"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary step metadata",
+    )
+
+
+class LoopTrigger(BaseModel):
+    """Defines how a loop can be triggered."""
+
+    model_config = ConfigDict(frozen=True)
+
+    trigger_type: str = Field(
+        default="manual",
+        description="Trigger type: manual, schedule, webhook, event",
+    )
+    config: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Trigger-specific configuration",
+    )
+
+
+class LoopSpec(BaseModel):
+    """Top-level declarative specification for an agent loop.
+
+    A ``LoopSpec`` is the single source of truth for loop configuration.
+    It is serializable to/from YAML and JSON, and validated by Pydantic v2.
+
+    Example YAML::
+
+        name: code-review
+        version: "1.0"
+        goal: Review pull request for correctness and style
+        pattern: supervisor_worker
+        agents:
+          - name: reviewer
+            capabilities: [code_review]
+        steps:
+          - name: review
+            agent: reviewer
+        policy:
+          max_turns: 10
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Loop identifier"
+    )
+    version: str = Field(
+        default="1.0", description="Semantic version of this spec"
+    )
+    description: str = Field(
+        default="", max_length=4096, description="Human-readable description"
+    )
+    goal: str = Field(
+        ..., min_length=1, description="The objective this loop achieves"
+    )
+    pattern: LoopPattern = Field(
+        default=LoopPattern.SEQUENTIAL,
+        description="Orchestration pattern",
+    )
+    trigger: LoopTrigger = Field(
+        default_factory=LoopTrigger,
+        description="How this loop is invoked",
+    )
+    agents: list[AgentRole] = Field(
+        ..., min_length=1, description="Agent participants"
+    )
+    tools: list[ToolSpec] = Field(
+        default_factory=list, description="Tools available in this loop"
+    )
+    steps: list[StepSpec] = Field(
+        ..., min_length=1, description="Ordered sequence of execution steps"
+    )
+    policy: Policy = Field(
+        default_factory=Policy,
+        description="Execution policy (turns, retries, gates, concurrency)",
+    )
+    stop_conditions: list[StopCondition] = Field(
+        default_factory=list,
+        description="Conditions that terminate the loop early",
+    )
+    output_schema: OutputSchema | None = Field(
+        default=None, description="Expected output schema"
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Initial context / variables injected into the loop",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary spec-level metadata",
+    )
+
+    # ------------------------------------------------------------------
+    # Convenience helpers
+    # ------------------------------------------------------------------
+
+    def get_agent(self, name: str) -> AgentRole | None:
+        """Look up an agent by name."""
+        return next((a for a in self.agents if a.name == name), None)
+
+    def get_step(self, name: str) -> StepSpec | None:
+        """Look up a step by name."""
+        return next((s for s in self.steps if s.name == name), None)
+
+    def get_tool(self, name: str) -> ToolSpec | None:
+        """Look up a tool by name."""
+        return next((t for t in self.tools if t.name == name), None)
+
+    def agent_names(self) -> list[str]:
+        """Return the list of agent names in definition order."""
+        return [a.name for a in self.agents]
+
+    def step_names(self) -> list[str]:
+        """Return the list of step names in definition order."""
+        return [s.name for s in self.steps]

loopengt/core/models/policy.py

@@ -0,0 +1,131 @@
+"""Policy, retry, timeout, and stop-condition definitions."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BackoffStrategy(StrEnum):
+    """Backoff strategy for retries."""
+
+    CONSTANT = "constant"
+    LINEAR = "linear"
+    EXPONENTIAL = "exponential"
+
+
+class RetryPolicy(BaseModel):
+    """Retry policy with configurable backoff."""
+
+    model_config = ConfigDict(frozen=True)
+
+    max_retries: int = Field(default=3, ge=0, description="Maximum number of retries")
+    initial_delay_seconds: float = Field(
+        default=1.0, gt=0, description="Delay before the first retry"
+    )
+    backoff: BackoffStrategy = Field(
+        default=BackoffStrategy.EXPONENTIAL,
+        description="Backoff strategy between retries",
+    )
+    max_delay_seconds: float = Field(
+        default=60.0, gt=0, description="Maximum delay cap"
+    )
+    jitter: bool = Field(
+        default=True, description="Add random jitter to delay"
+    )
+    retryable_errors: list[str] = Field(
+        default_factory=lambda: ["TimeoutError", "ConnectionError"],
+        description="Error class names eligible for retry",
+    )
+
+    def compute_delay(self, attempt: int) -> float:
+        """Compute the delay for a given attempt number (0-indexed).
+
+        Returns the raw delay *before* jitter is applied.
+        """
+        if self.backoff == BackoffStrategy.CONSTANT:
+            delay = self.initial_delay_seconds
+        elif self.backoff == BackoffStrategy.LINEAR:
+            delay = self.initial_delay_seconds * (attempt + 1)
+        else:  # exponential
+            delay = self.initial_delay_seconds * (2**attempt)
+        return min(delay, self.max_delay_seconds)
+
+
+class VerificationGate(BaseModel):
+    """A gate that must pass before the loop proceeds past a given step.
+
+    Gates are evaluated after a step completes.  If the gate fails and
+    ``on_failure`` is ``"retry"``, the step is re-run up to the retry
+    budget.  If ``"abort"``, the loop is stopped.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Gate identifier"
+    )
+    description: str = Field(default="", description="What this gate checks")
+    condition: str = Field(
+        ...,
+        description=(
+            "A Python expression or JMESPath query evaluated against "
+            "the step result.  Must evaluate to a truthy value to pass."
+        ),
+    )
+    on_failure: str = Field(
+        default="retry",
+        description="Action on failure: 'retry' or 'abort'",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary metadata",
+    )
+
+
+class Policy(BaseModel):
+    """Top-level policy governing loop execution behaviour.
+
+    Controls how many turns are allowed, retry budgets, timeouts, and
+    verification gates that must pass between steps.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    max_turns: int = Field(
+        default=50,
+        ge=1,
+        description="Hard limit on total loop turns across all agents",
+    )
+    max_total_time_seconds: float = Field(
+        default=3600.0,
+        gt=0,
+        description="Maximum wall-clock time for the entire loop",
+    )
+    retry: RetryPolicy = Field(
+        default_factory=RetryPolicy,
+        description="Default retry policy for steps without their own",
+    )
+    verification_gates: list[VerificationGate] = Field(
+        default_factory=list,
+        description="Ordered list of verification gates",
+    )
+    allow_parallel: bool = Field(
+        default=False,
+        description="Whether the scheduler may execute independent steps concurrently",
+    )
+    max_concurrency: int = Field(
+        default=4,
+        ge=1,
+        description="Maximum concurrent steps when parallel execution is enabled",
+    )
+    fail_fast: bool = Field(
+        default=True,
+        description="Abort the loop on the first unrecoverable error",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary policy metadata",
+    )