fifty-agent-sdk 1.1.0__py3-none-any.whl

fifty_agent_sdk/__init__.py

@@ -0,0 +1,191 @@
+"""fifty-agent-sdk — Production-grade reusable agent loop SDK.
+
+Foundation layer: typed errors, Pydantic v2 message types, the
+:class:`LLMClient` protocol, an OpenAI-compatible adapter, and a system
+prompt template builder. Higher layers (parser, tool registry, ReACT loop,
+state stores) build on these contracts in subsequent briefs.
+
+Optional extra surface
+    :class:`SqlStateStore` and :data:`sql_metadata`, plus
+    :class:`SqlAuditSink` and :data:`audit_metadata` (all the ``sql``
+    extra, ``pip install 'fifty-agent-sdk[sql]'``), and :class:`RedisStateStore`
+    (the ``redis`` extra, ``pip install 'fifty-agent-sdk[redis]'``) are
+    re-exported lazily. Importing :mod:`fifty_agent_sdk` itself pulls neither
+    SQLAlchemy nor redis-py. First access to one of these symbols triggers
+    its import and raises a clear :class:`ImportError` if the relevant
+    extra is missing.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fifty_agent_sdk.audit import AuditEvent, AuditSink, ConsoleAuditSink
+from fifty_agent_sdk.errors import (
+    AgentSdkError,
+    LLMError,
+    MaxIterationsExceeded,
+    MCPError,
+    ParserError,
+    StateStoreError,
+    ToolNotFound,
+    ToolTimeout,
+)
+from fifty_agent_sdk.llm import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    FinishReason,
+    LLMClient,
+    OpenAICompatibleClient,
+    Role,
+    ToolCall,
+    Usage,
+)
+from fifty_agent_sdk.loop import AgentLoop
+from fifty_agent_sdk.mcp import MCPClient, MCPClientConfig, MCPToolDef
+from fifty_agent_sdk.observability import Hooks
+from fifty_agent_sdk.parser import (
+    FinalAnswer,
+    JsonModeParser,
+    NativeToolsParser,
+    NativeToolsParserStub,
+    Parser,
+    ParseResult,
+    ProseModeParser,
+    ThoughtAction,
+)
+from fifty_agent_sdk.prompts import (
+    JSON_MODE_OUTPUT_FORMAT,
+    PROSE_MODE_OUTPUT_FORMAT,
+    PromptSections,
+    json_mode_template,
+    prose_mode_template,
+    render_system_prompt,
+)
+from fifty_agent_sdk.runner import AgentRunner
+from fifty_agent_sdk.safety import SafetyConfig
+from fifty_agent_sdk.state import MemoryStateStore, StateStore
+from fifty_agent_sdk.streaming import (
+    ActionEvent,
+    AgentEvent,
+    ErrorEvent,
+    FinalEvent,
+    ObservationEvent,
+    ThoughtEvent,
+    TokenEvent,
+    ToolFailedEvent,
+    ToolProgressEvent,
+    ToolStartedEvent,
+)
+from fifty_agent_sdk.tools import (
+    InProcProvider,
+    MCPProvider,
+    RefreshSummary,
+    Registry,
+    Tool,
+    ToolResult,
+    ToolSchema,
+    tool,
+)
+
+if TYPE_CHECKING:
+    from fifty_agent_sdk.audit.sql import SqlAuditSink, audit_metadata
+    from fifty_agent_sdk.state.redis import RedisStateStore
+    from fifty_agent_sdk.state.sql import SqlStateStore, sql_metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "JSON_MODE_OUTPUT_FORMAT",
+    "PROSE_MODE_OUTPUT_FORMAT",
+    "ActionEvent",
+    "AgentEvent",
+    "AgentLoop",
+    "AgentRunner",
+    "AgentSdkError",
+    "AuditEvent",
+    "AuditSink",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "ConsoleAuditSink",
+    "ErrorEvent",
+    "FinalAnswer",
+    "FinalEvent",
+    "FinishReason",
+    "Hooks",
+    "InProcProvider",
+    "JsonModeParser",
+    "LLMClient",
+    "LLMError",
+    "MCPClient",
+    "MCPClientConfig",
+    "MCPError",
+    "MCPProvider",
+    "MCPToolDef",
+    "MaxIterationsExceeded",
+    "MemoryStateStore",
+    "NativeToolsParser",
+    "NativeToolsParserStub",
+    "ObservationEvent",
+    "OpenAICompatibleClient",
+    "ParseResult",
+    "Parser",
+    "ParserError",
+    "PromptSections",
+    "ProseModeParser",
+    "RedisStateStore",
+    "RefreshSummary",
+    "Registry",
+    "Role",
+    "SafetyConfig",
+    "SqlAuditSink",
+    "SqlStateStore",
+    "StateStore",
+    "StateStoreError",
+    "ThoughtAction",
+    "ThoughtEvent",
+    "TokenEvent",
+    "Tool",
+    "ToolCall",
+    "ToolFailedEvent",
+    "ToolNotFound",
+    "ToolProgressEvent",
+    "ToolResult",
+    "ToolSchema",
+    "ToolStartedEvent",
+    "ToolTimeout",
+    "Usage",
+    "audit_metadata",
+    "json_mode_template",
+    "prose_mode_template",
+    "render_system_prompt",
+    "sql_metadata",
+    "tool",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import optional-extra surface symbols on first access.
+
+    ``SqlStateStore`` / ``sql_metadata`` and ``SqlAuditSink`` /
+    ``audit_metadata`` require the optional ``sql`` extra;
+    ``RedisStateStore`` requires the ``redis`` extra. Routing access
+    through this hook keeps ``import fifty_agent_sdk`` free of SQLAlchemy and
+    redis-py, and surfaces a clear :class:`ImportError` only when the
+    symbols are actually used without the extra installed.
+    """
+    if name in {"SqlStateStore", "sql_metadata"}:
+        from fifty_agent_sdk.state import sql
+
+        return getattr(sql, name)
+    if name in {"SqlAuditSink", "audit_metadata"}:
+        from fifty_agent_sdk.audit import sql as audit_sql
+
+        return getattr(audit_sql, name)
+    if name == "RedisStateStore":
+        from fifty_agent_sdk.state import redis
+
+        return redis.RedisStateStore
+    raise AttributeError(f"module 'fifty_agent_sdk' has no attribute {name!r}")

fifty_agent_sdk/audit/__init__.py

@@ -0,0 +1,45 @@
+"""Audit subpackage: pluggable, tamper-evident action provenance.
+
+Re-exports the :class:`AuditEvent` model, the :class:`AuditSink` protocol,
+and the dependency-free :class:`ConsoleAuditSink`. The durable SQL backend
+(:class:`SqlAuditSink`) with its Alembic :data:`audit_metadata` symbol is
+re-exported lazily via a module-level ``__getattr__`` — it requires the
+optional ``sql`` extra, so ``import fifty_agent_sdk.audit`` itself does NOT pull
+SQLAlchemy.
+
+Accessing :data:`SqlAuditSink` or :data:`audit_metadata` without
+``fifty-agent-sdk[sql]`` installed raises a clear :class:`ImportError` referencing
+the extras line.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fifty_agent_sdk.audit.console import ConsoleAuditSink
+from fifty_agent_sdk.audit.protocol import AuditEvent, AuditSink
+
+if TYPE_CHECKING:
+    from fifty_agent_sdk.audit.sql import SqlAuditSink, audit_metadata
+
+__all__ = [
+    "AuditEvent",
+    "AuditSink",
+    "ConsoleAuditSink",
+    "SqlAuditSink",
+    "audit_metadata",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import optional-extra surface symbols on first access.
+
+    Keeps the package's eager import surface free of SQLAlchemy. When the
+    ``sql`` extra is not installed, importing the backing module (triggered
+    here) raises a documented :class:`ImportError`.
+    """
+    if name in {"SqlAuditSink", "audit_metadata"}:
+        from fifty_agent_sdk.audit import sql
+
+        return getattr(sql, name)
+    raise AttributeError(f"module 'fifty_agent_sdk.audit' has no attribute {name!r}")

fifty_agent_sdk/audit/console.py

@@ -0,0 +1,69 @@
+"""ConsoleAuditSink — structured-log audit sink for dev / single-tenant use.
+
+:class:`ConsoleAuditSink` is the zero-dependency :class:`AuditSink`
+implementation. It emits each :class:`AuditEvent` as one ``INFO`` structlog
+record under the fixed logger name ``fifty_agent_sdk.audit``.
+
+It is the right choice when audit logs are already centralized (a single
+deployment shipping structlog output to a log aggregator) and a separate
+audit database is not warranted. It is NOT tamper-evident on its own — the
+durability and integrity guarantees are whatever the surrounding log
+pipeline provides. For a durable, queryable trail use
+:class:`fifty_agent_sdk.audit.sql.SqlAuditSink`.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+import structlog
+
+from fifty_agent_sdk.audit.protocol import AuditEvent
+
+_log: Final = structlog.get_logger("fifty_agent_sdk.audit")
+"""Module-level structured logger.
+
+Bound to the fixed name ``fifty_agent_sdk.audit`` (NOT ``__name__``) so every
+audit record — from this sink and from :mod:`fifty_agent_sdk.audit.sql` — shares
+one logger name a consumer can route or filter on.
+"""
+
+
+class ConsoleAuditSink:
+    """An :class:`AuditSink` that writes each event to structlog at ``INFO``.
+
+    Satisfies :class:`fifty_agent_sdk.audit.protocol.AuditSink` structurally (no
+    explicit inheritance needed thanks to ``@runtime_checkable``).
+
+    No constructor arguments — the sink is stateless and safe to share
+    across concurrent runs (structlog loggers are themselves thread- and
+    task-safe).
+
+    Caution:
+        Not tamper-evident on its own. The integrity of the trail is only
+        as strong as the log pipeline the records are shipped through. Use
+        :class:`fifty_agent_sdk.audit.sql.SqlAuditSink` when a durable, queryable,
+        append-only record is required.
+    """
+
+    async def record(self, event: AuditEvent) -> None:
+        """Emit ``event`` as a single ``INFO`` structlog record.
+
+        The record's event name is ``audit.event``; the
+        :class:`AuditEvent` fields are spread as structured key/values
+        (``timestamp`` rendered as an ISO-8601 string).
+
+        Args:
+            event: The :class:`AuditEvent` to log.
+        """
+        _log.info(
+            "audit.event",
+            session_id=event.session_id,
+            user_id=event.user_id,
+            event_type=event.event_type,
+            timestamp=event.timestamp.isoformat(),
+            payload=event.payload,
+        )
+
+
+__all__ = ["ConsoleAuditSink"]

fifty_agent_sdk/audit/protocol.py

@@ -0,0 +1,112 @@
+"""AuditSink protocol — pluggable, tamper-evident action provenance.
+
+The :class:`AuditSink` protocol is the SDK's abstraction for capturing a
+durable record of every agent action. :class:`fifty_agent_sdk.runner.AgentRunner`
+emits an :class:`AuditEvent` at four points of every ``run()``: session
+start, each tool invocation, the final answer, and any error.
+
+Implementations may write to structured logs (see
+:class:`fifty_agent_sdk.audit.console.ConsoleAuditSink` — the dev default), a SQL
+table (:class:`fifty_agent_sdk.audit.sql.SqlAuditSink`), or any other backend.
+
+Contract invariants
+    * **Ordering.** :meth:`AuditSink.record` is called in the order events
+      occur within a run. Implementations MUST NOT reorder events; the
+      append-only nature of the record is a load-bearing property for any
+      consumer treating it as a compliance trail.
+    * **Concurrency.** :meth:`AuditSink.record` MUST be safe to call from
+      multiple concurrent runs sharing one sink instance. Implementations
+      that serialize do so internally; the caller does not lock.
+    * **Failure is the caller's to swallow.** A raising :meth:`record` is
+      tolerated by :class:`AgentRunner`, which catches the exception, logs a
+      ``WARNING``, and continues — an audit-sink outage MUST NOT abort a
+      live agent run. Implementations SHOULD still raise on backend failure
+      (rather than silently dropping) so the gap is visible in the Runner's
+      ``audit.emit_failed`` log line.
+    * **Tamper-evidence is the sink's job.** "Tamper-evident" is a property
+      of the *sink's storage* (append-only table, hash-chaining, WORM
+      bucket), not of the emission path. The emission path's contract is
+      best-effort delivery plus a loud warning when delivery fails.
+    * **No secrets in the payload.** Consumers and tools MUST NOT place
+      credentials or raw secrets into :attr:`AuditEvent.payload`; the
+      payload is persisted verbatim and may appear in logs.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AuditEvent(BaseModel):
+    """A single audited agent action.
+
+    The provider-agnostic shape passed to every :class:`AuditSink`. Like the
+    other SDK models it sets ``extra="forbid"`` so a typo'd field is caught
+    at construction rather than silently dropped.
+
+    Attributes:
+        session_id: Opaque session identifier the action belongs to.
+        user_id: Optional end-user identifier. The Runner does not have a
+            user-id channel today and always emits ``None``; consumers
+            wanting per-user attribution set it via a wrapping sink.
+        timestamp: When the action occurred (timezone-aware UTC). The Runner
+            stamps this at emission time — it is the *action* time, not the
+            time the row was persisted.
+        event_type: Short tag for the kind of action. The four values the
+            Runner emits are ``"session_start"``, ``"tool_invocation"``,
+            ``"final_answer"``, and ``"error"``; the field is a free-form
+            string (not a ``Literal``) so consumers can emit their own
+            event types through the same sink.
+        payload: Structured, event-specific detail. Always a real ``dict``
+            (never ``None``); defaults to ``{}``. MUST NOT contain
+            credentials or raw secrets — it is persisted and logged
+            verbatim.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: str
+    user_id: str | None = None
+    timestamp: datetime
+    event_type: str
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+@runtime_checkable
+class AuditSink(Protocol):
+    """Pluggable audit-trail backend.
+
+    See the module docstring for the full contract. Implementations are
+    duck-typed: any class providing the single async method below with a
+    matching signature satisfies :func:`isinstance` against
+    :class:`AuditSink` thanks to ``@runtime_checkable``.
+
+    Note:
+        ``@runtime_checkable`` :class:`Protocol` instances only check for
+        method *presence*, not signature compatibility. Mypy ``--strict``
+        catches signature mismatches at type-check time.
+    """
+
+    async def record(self, event: AuditEvent) -> None:
+        """Persist a single :class:`AuditEvent`.
+
+        Called once per audited action, in occurrence order. Implementations
+        MUST NOT reorder events and MUST be safe to call concurrently from
+        multiple runs sharing the sink.
+
+        Args:
+            event: The :class:`AuditEvent` to record.
+
+        Raises:
+            Exception: Implementations MAY raise on backend failure. The
+                :class:`fifty_agent_sdk.runner.AgentRunner` catches the exception,
+                logs a ``WARNING``, and continues — a sink failure never
+                aborts an agent run.
+        """
+        ...
+
+
+__all__ = ["AuditEvent", "AuditSink"]