agentlings 0.2.0__py3-none-any.whl

agentlings/config.py

@@ -0,0 +1,260 @@
+"""Agent configuration from environment variables and optional YAML agent definition."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Literal
+
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryConfig(BaseModel):
+    """Memory subsystem configuration.
+
+    Attributes:
+        token_budget: Maximum tokens for the memory block injected into the system prompt.
+        injection_prompt: Override template for the memory injection block.
+            Receives ``{entries}`` placeholder. ``None`` uses the built-in default.
+        inject_into_prompt: When ``False``, the memory store is still active and
+            the ``memory_*`` tools are still callable, but no memory block is
+            stapled into the system prompt. The agent must read memory
+            explicitly via the tool. Useful for small/local models where the
+            prompt budget is precious.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    token_budget: int = 2000
+    injection_prompt: str | None = None
+    inject_into_prompt: bool = True
+
+
+class SleepConfig(BaseModel):
+    """Nightly sleep cycle configuration.
+
+    Attributes:
+        enabled: When ``False``, the sleep cycle is not scheduled even if
+            the block is present. Set this for backends that lack the
+            Anthropic batches API (e.g. Ollama's compatibility layer).
+        schedule: Cron expression for when to run (default 2am daily).
+        journal_retention_days: How long to keep journal files.
+        conversation_retention_days: How long to keep JSONL conversation files.
+        memory_max_entries: Hard cap on memory entries after consolidation.
+        model: Model override for sleep LLM calls (``None`` uses agent default).
+        summary_prompt: Override for the per-conversation summary prompt.
+        consolidation_prompt: Override for the REM consolidation prompt.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    enabled: bool = True
+    schedule: str = "0 2 * * *"
+    journal_retention_days: int = 30
+    conversation_retention_days: int = 14
+    memory_max_entries: int = 50
+    model: str | None = None
+    summary_prompt: str | None = None
+    consolidation_prompt: str | None = None
+
+
+class TelemetryConfig(BaseModel):
+    """OpenTelemetry configuration.
+
+    Attributes:
+        enabled: Whether telemetry is active.
+        endpoint: OTLP collector endpoint URL.
+        protocol: Collector protocol (``"http"`` or ``"grpc"``).
+        service_name: Service name for spans and metrics.
+        insecure: Disable TLS for the collector connection.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    enabled: bool = False
+    endpoint: str = "http://localhost:4318"
+    protocol: str = "http"
+    service_name: str = "agentling"
+    insecure: bool = True
+    headers: dict[str, str] = Field(default_factory=dict)
+
+
+class SkillConfig(BaseModel):
+    """A skill advertised in the Agent Card.
+
+    Attributes:
+        id: Unique skill identifier.
+        name: Human-readable skill name.
+        description: What this skill does.
+        tags: Searchable tags for discovery.
+    """
+
+    id: str
+    name: str
+    description: str
+    tags: list[str] = Field(default_factory=list)
+
+
+class AgentDefinition(BaseModel):
+    """Agent identity and behaviour loaded from YAML.
+
+    Attributes:
+        name: Agent name used in the Agent Card and MCP tool.
+        description: Agent description for discovery.
+        tools: Tool names or groups to enable (e.g. ``["bash", "filesystem"]``).
+        skills: Skills to advertise in the Agent Card.
+        system_prompt: The system prompt sent to the LLM.
+        bash_timeout: Default timeout in seconds for bash tool commands.
+        data_dir_awareness: When ``True`` (default), append a system-prompt
+            block telling the agent where its data directory lives and how
+            to read journals and conversation logs. Set to ``False`` for
+            agents without filesystem tools or when the prompt budget is
+            tight (e.g. small local models).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str = "agentling"
+    description: str = "A lightweight AI agent"
+    tools: list[str] = Field(default_factory=list)
+    skills: list[SkillConfig] = Field(default_factory=list)
+    system_prompt: str | None = None
+    bash_timeout: int = Field(ge=1, default=30)
+    data_dir_awareness: bool = True
+    memory: MemoryConfig | None = None
+    sleep: SleepConfig | None = None
+    telemetry: TelemetryConfig | None = None
+
+
+class AgentConfig(BaseSettings):
+    """Runtime configuration for an agentling instance.
+
+    Secrets and runtime settings come from environment variables.
+    Agent identity (name, description, skills, tools, system prompt) comes
+    from a YAML file pointed to by ``AGENT_CONFIG``.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    anthropic_api_key: str = ""
+    anthropic_base_url: str | None = None
+    agent_api_key: str = ""
+    agent_model: str = "claude-sonnet-4-6"
+    agent_max_tokens: int = 4096
+    agent_host: str = "0.0.0.0"
+    agent_port: int = 8420
+    agent_data_dir: Path = Path("./data")
+    agent_log_level: str = "INFO"
+    agent_llm_backend: Literal["anthropic", "mock"] = "anthropic"
+    agent_external_url: str | None = None
+    agent_config: str | None = None
+    agent_otel_endpoint: str | None = None
+    agent_otel_protocol: str = "http"
+    agent_otel_insecure: bool = True
+    agent_otel_headers: str = ""
+    agent_task_await_seconds: int = 60
+
+    _definition: AgentDefinition = AgentDefinition()
+
+    @model_validator(mode="after")
+    def _init(self) -> AgentConfig:
+        self.agent_data_dir.mkdir(parents=True, exist_ok=True)
+        if self.agent_config:
+            self._definition = _load_definition(self.agent_config)
+        return self
+
+    @property
+    def definition(self) -> AgentDefinition:
+        """The agent definition loaded from YAML (or defaults)."""
+        return self._definition
+
+    @property
+    def agent_name(self) -> str:
+        """Agent name from the YAML definition."""
+        return self._definition.name
+
+    @property
+    def agent_description(self) -> str:
+        """Agent description from the YAML definition."""
+        return self._definition.description
+
+    @property
+    def enabled_tools(self) -> list[str]:
+        """Tool names/groups to activate from the YAML definition."""
+        return self._definition.tools
+
+    @property
+    def system_prompt(self) -> str | None:
+        """System prompt from the YAML definition."""
+        return self._definition.system_prompt
+
+    @property
+    def skills(self) -> list[SkillConfig]:
+        """Skills to advertise from the YAML definition."""
+        return self._definition.skills
+
+    @property
+    def memory_config(self) -> MemoryConfig | None:
+        """Memory configuration from the YAML definition."""
+        return self._definition.memory
+
+    @property
+    def sleep_config(self) -> SleepConfig | None:
+        """Sleep cycle configuration from the YAML definition."""
+        return self._definition.sleep
+
+    @property
+    def telemetry_config(self) -> TelemetryConfig | None:
+        """Telemetry configuration, with env vars overriding YAML values."""
+        base = self._definition.telemetry
+        if self.agent_otel_endpoint:
+            if base is None:
+                base = TelemetryConfig(enabled=True)
+            updates: dict[str, Any] = {
+                "enabled": True,
+                "endpoint": self.agent_otel_endpoint,
+                "protocol": self.agent_otel_protocol,
+                "insecure": self.agent_otel_insecure,
+            }
+            if self.agent_otel_headers:
+                updates["headers"] = _parse_headers(self.agent_otel_headers)
+            base = base.model_copy(update=updates)
+        return base
+
+
+def _parse_headers(raw: str) -> dict[str, str]:
+    """Parse a comma-separated ``key=value`` string into a headers dict.
+
+    Example: ``"Authorization=Bearer tok,X-Custom=val"``
+    """
+    headers: dict[str, str] = {}
+    for pair in raw.split(","):
+        pair = pair.strip()
+        if "=" in pair:
+            k, v = pair.split("=", 1)
+            headers[k.strip()] = v.strip()
+    return headers
+
+
+def _load_definition(path: str) -> AgentDefinition:
+    """Load an ``AgentDefinition`` from a YAML file.
+
+    Args:
+        path: Path to the YAML configuration file.
+
+    Returns:
+        A validated ``AgentDefinition``.
+    """
+    raw = Path(path).read_text(encoding="utf-8")
+    data = yaml.safe_load(raw) or {}
+    logger.info("loaded agent definition from %s", path)
+    return AgentDefinition.model_validate(data)

agentlings/core/__init__.py

@@ -0,0 +1 @@
+"""Core engine: message loop, LLM client, conversation store, and system prompt."""

agentlings/core/completion.py

@@ -0,0 +1,219 @@
+"""Reusable LLM completion cycle: call model, execute tools, repeat until terminal response."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+from agentlings.core.llm import BaseLLMClient, LLMResponse
+from agentlings.core.telemetry import get_meter, otel_span
+from agentlings.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class CancellationRequested(Exception):
+    """Raised inside ``run_completion`` when a cancel callback returns ``True``.
+
+    Callers are expected to catch this and apply their own cancel terminal
+    semantics (e.g. writing a ``TaskCancelled`` marker). The ``partial``
+    attribute carries a ``CompletionResult`` with turns completed so far.
+    """
+
+    def __init__(self, message: str, partial: "CompletionResult") -> None:
+        super().__init__(message)
+        self.partial = partial
+
+@functools.lru_cache(maxsize=1)
+def _get_metrics() -> dict[str, Any]:
+    m = get_meter()
+    return {
+        "duration": m.create_histogram(
+            "agentling.completion.duration_seconds",
+            description="End-to-end completion cycle duration",
+        ),
+        "turns": m.create_histogram(
+            "agentling.completion.turns",
+            description="Number of LLM turns per completion cycle",
+        ),
+        "tool_calls": m.create_counter(
+            "agentling.tool.calls",
+            description="Total tool invocations",
+        ),
+        "tool_errors": m.create_counter(
+            "agentling.tool.errors",
+            description="Tool execution errors",
+        ),
+    }
+
+
+@dataclass
+class CompletionTurn:
+    """A single assistant response and its corresponding tool results (if any).
+
+    Attributes:
+        response: The LLM response for this turn.
+        tool_results: Tool result content blocks returned to the LLM, empty for terminal turns.
+    """
+
+    response: LLMResponse
+    tool_results: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class CompletionResult:
+    """Result of running the LLM completion cycle.
+
+    Attributes:
+        content: Anthropic-format content blocks from the final LLM response.
+        stop_reason: Why the model stopped generating.
+        turns: Every turn in the cycle, each pairing an LLM response with its tool results.
+    """
+
+    content: list[dict[str, Any]]
+    stop_reason: str | None = None
+    turns: list[CompletionTurn] = field(default_factory=list)
+
+
+async def run_completion(
+    llm: BaseLLMClient,
+    system: list[dict[str, Any]],
+    messages: list[dict[str, Any]],
+    tools: ToolRegistry,
+    turn_callback: Callable[[CompletionTurn], Awaitable[None]] | None = None,
+    should_cancel: Callable[[], bool] | None = None,
+) -> CompletionResult:
+    """Run the LLM in a loop, executing tool calls until a terminal text response.
+
+    This is the core interaction cycle extracted from the message loop so that
+    both conversation handling and the sleep cycle can reuse it.
+
+    Args:
+        llm: The LLM client to use for completions.
+        system: System prompt blocks.
+        messages: Conversation messages (mutated in place with tool results).
+        tools: Registry of available tools.
+        turn_callback: Optional async callback invoked after each completed turn
+            (with the turn that just concluded). Used by the task engine to
+            journal per-turn progress into the sub-journal.
+        should_cancel: Optional synchronous predicate checked at cooperative
+            checkpoints — after each LLM call, before each tool batch, and
+            after each tool batch. When it returns ``True``,
+            ``CancellationRequested`` is raised and all partial progress so
+            far is available in ``CompletionResult`` via a raised exception
+            attribute.
+
+    Returns:
+        The final response content and all intermediate responses.
+
+    Raises:
+        CancellationRequested: If ``should_cancel`` returns ``True`` at a
+            checkpoint. The exception carries a ``partial`` attribute with a
+            ``CompletionResult`` containing turns completed so far.
+    """
+    tool_schemas = tools.list_schemas()
+    turns: list[CompletionTurn] = []
+    cycle_start = time.monotonic()
+    metrics = _get_metrics()
+
+    def _check_cancel() -> None:
+        if should_cancel is not None and should_cancel():
+            partial = CompletionResult(
+                content=turns[-1].response.content if turns else [],
+                stop_reason="cancelled",
+                turns=turns,
+            )
+            raise CancellationRequested("cancellation requested", partial)
+
+    with otel_span("agentling.completion") as cycle_span:
+        while True:
+            turn_number = len(turns) + 1
+
+            with otel_span("agentling.completion.llm_call", {"completion.turn": turn_number}):
+                response = await llm.complete(system, messages, tool_schemas)
+
+            _check_cancel()
+
+            has_tool_use = any(
+                block.get("type") == "tool_use" for block in response.content
+            )
+
+            if not has_tool_use:
+                terminal_turn = CompletionTurn(response=response)
+                turns.append(terminal_turn)
+                if turn_callback is not None:
+                    await turn_callback(terminal_turn)
+                elapsed = time.monotonic() - cycle_start
+                logger.info(
+                    "completion finished: %d turn(s) in %.1fs, stop_reason=%s",
+                    len(turns), elapsed, response.stop_reason,
+                )
+                cycle_span.set_attribute("completion.turns", len(turns))
+                cycle_span.set_attribute("completion.stop_reason", response.stop_reason or "unknown")
+                cycle_span.set_attribute("completion.duration_s", round(elapsed, 2))
+                metrics["duration"].record(elapsed)
+                metrics["turns"].record(len(turns))
+                return CompletionResult(
+                    content=response.content,
+                    stop_reason=response.stop_reason,
+                    turns=turns,
+                )
+
+            messages.append({"role": "assistant", "content": response.content})
+
+            tool_calls = [b for b in response.content if b.get("type") == "tool_use"]
+            logger.info(
+                "turn %d: executing %d tool(s): %s",
+                turn_number, len(tool_calls),
+                ", ".join(b["name"] for b in tool_calls),
+            )
+
+            _check_cancel()
+
+            async def _exec_tool(block: dict[str, Any]) -> dict[str, Any]:
+                try:
+                    with otel_span("agentling.completion.tool_exec", {
+                        "tool.name": block["name"],
+                        "completion.turn": turn_number,
+                    }) as tool_span:
+                        result = await tools.execute(block["name"], block.get("input", {}))
+                        tool_span.set_attribute("tool.is_error", result.is_error)
+
+                    tool_attrs = {"tool.name": block["name"]}
+                    metrics["tool_calls"].add(1, tool_attrs)
+                    if result.is_error:
+                        metrics["tool_errors"].add(1, tool_attrs)
+                        logger.warning("tool %s returned error: %.200s", block["name"], result.output)
+
+                    return {
+                        "type": "tool_result",
+                        "tool_use_id": block["id"],
+                        "content": result.output,
+                        "is_error": result.is_error,
+                    }
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    logger.exception("unhandled exception in tool %s", block["name"])
+                    metrics["tool_calls"].add(1, {"tool.name": block["name"]})
+                    metrics["tool_errors"].add(1, {"tool.name": block["name"]})
+                    return {
+                        "type": "tool_result",
+                        "tool_use_id": block["id"],
+                        "content": f"Tool {block['name']} failed with an internal error",
+                        "is_error": True,
+                    }
+
+            tool_results = list(await asyncio.gather(*(_exec_tool(b) for b in tool_calls)))
+
+            _check_cancel()
+
+            turn = CompletionTurn(response=response, tool_results=tool_results)
+            turns.append(turn)
+            if turn_callback is not None:
+                await turn_callback(turn)
+            messages.append({"role": "user", "content": tool_results})