locus-sdk 0.2.0__py3-none-any.whl

locus/__init__.py

@@ -0,0 +1,241 @@
+# Copyright (c) 2025, 2026 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v1.0 as shown at
+# https://oss.oracle.com/licenses/upl/
+
+"""
+Locus - A zero-LangChain agentic SDK.
+
+Built-in Reflexion, Grounding Evaluation, and production-grade orchestration.
+100% Pydantic. No magic.
+
+Usage:
+    from locus import Agent, tool
+
+    @tool
+    def search(query: str) -> str:
+        '''Search the knowledge base.'''
+        return "results..."
+
+    agent = Agent(
+        model="openai:gpt-4o",  # or oci:cohere.command-r-plus
+        tools=[search],
+        system_prompt="You are a helpful assistant.",
+    )
+
+    async for event in agent.run("Find information about X"):
+        print(event)
+"""
+
+from locus.core.config import LocusSettings
+from locus.core.errors import LocusError
+from locus.core.events import (
+    GroundingEvent,
+    LocusEvent,
+    ReflectEvent,
+    TerminateEvent,
+    ThinkEvent,
+    ToolCompleteEvent,
+    ToolStartEvent,
+)
+from locus.core.messages import Message, Role, ToolCall
+from locus.core.state import AgentState
+from locus.tools.context import ToolContext
+from locus.tools.decorator import tool
+
+
+# Lazy import mapping for optional dependencies
+_LAZY_IMPORTS = {
+    "Agent": ("locus.agent.agent", "Agent"),
+    "AgentConfig": ("locus.agent.config", "AgentConfig"),
+    "AgentResult": ("locus.agent.result", "AgentResult"),
+    # Composition primitives — graph-free orchestration shapes.
+    "SequentialPipeline": ("locus.agent.composition", "SequentialPipeline"),
+    "ParallelPipeline": ("locus.agent.composition", "ParallelPipeline"),
+    "LoopAgent": ("locus.agent.composition", "LoopAgent"),
+    # Multi-agent primitives — graph + handoff + orchestrator/specialist.
+    "StateGraph": ("locus.multiagent.graph", "StateGraph"),
+    "GraphConfig": ("locus.multiagent.graph", "GraphConfig"),
+    "START": ("locus.multiagent.graph", "START"),
+    "END": ("locus.multiagent.graph", "END"),
+    "Send": ("locus.core.send", "Send"),
+    "Handoff": ("locus.multiagent.handoff", "Handoff"),
+    "HandoffContext": ("locus.multiagent.handoff", "HandoffContext"),
+    "HandoffReason": ("locus.multiagent.handoff", "HandoffReason"),
+    "create_handoff_agent": ("locus.multiagent.handoff", "create_handoff_agent"),
+    "create_handoff_manager": ("locus.multiagent.handoff", "create_handoff_manager"),
+    "Orchestrator": ("locus.multiagent.orchestrator", "Orchestrator"),
+    "RoutingDecision": ("locus.multiagent.orchestrator", "RoutingDecision"),
+    "create_orchestrator": ("locus.multiagent.orchestrator", "create_orchestrator"),
+    "Specialist": ("locus.multiagent.specialist", "Specialist"),
+    # Public name "Reflexion" maps to the actual class "Reflector". The
+    # mismatch was an import error on locus 0.1.0 — keep the alias so existing
+    # docs / code that does ``from locus import Reflexion`` keeps working.
+    "Reflexion": ("locus.reasoning.reflexion", "Reflector"),
+    "Reflector": ("locus.reasoning.reflexion", "Reflector"),
+    "GroundingEvaluator": ("locus.reasoning.grounding", "GroundingEvaluator"),
+    "CausalChain": ("locus.reasoning.causal", "CausalChain"),
+    "HookProvider": ("locus.hooks.provider", "HookProvider"),
+    "HookRegistry": ("locus.hooks.registry", "HookRegistry"),
+    # RAG
+    "RAGRetriever": ("locus.rag.retriever", "RAGRetriever"),
+    "OCIEmbeddings": ("locus.rag.embeddings.oci", "OCIEmbeddings"),
+    "OracleVectorStore": ("locus.rag.stores.oracle", "OracleVectorStore"),
+    # PRISM router — bounded-graph generation atop locus primitives.
+    "Router": ("locus.router.runtime", "Router"),
+    "GoalFrame": ("locus.router.goal_frame", "GoalFrame"),
+    "TaskType": ("locus.router.goal_frame", "TaskType"),
+    "Risk": ("locus.router.goal_frame", "Risk"),
+    "Complexity": ("locus.router.goal_frame", "Complexity"),
+    "Capability": ("locus.router.capability", "Capability"),
+    "CapabilityIndex": ("locus.router.capability", "CapabilityIndex"),
+    "Protocol": ("locus.router.protocol", "Protocol"),
+    "ProtocolRegistry": ("locus.router.protocol", "ProtocolRegistry"),
+    "PolicyGate": ("locus.router.policy", "PolicyGate"),
+    "PolicyVerdict": ("locus.router.policy", "PolicyVerdict"),
+    "CognitiveCompiler": ("locus.router.compiler", "CognitiveCompiler"),
+    "RunnableResult": ("locus.router.runnable", "RunnableResult"),
+    "SkillIndex": ("locus.router.skill_index", "SkillIndex"),
+    "builtin_protocols": ("locus.router.protocol", "builtin_protocols"),
+    # Deep research — research-shaped Agent factory + provider protocol.
+    # Submodule is ``locus.deepagent`` (Pythonic path-name convention).
+    # Factory is ``create_deepagent`` (matches ``create_orchestrator``,
+    # ``create_handoff_agent`` — the existing locus naming for "build me
+    # a configured X").
+    "create_deepagent": ("locus.deepagent", "create_deepagent"),
+    "create_research_workflow": ("locus.deepagent.workflow", "create_research_workflow"),
+    "make_execute_node": ("locus.deepagent.workflow", "make_execute_node"),
+    "make_causal_inference_node": ("locus.deepagent.workflow", "make_causal_inference_node"),
+    "make_summarize_node": ("locus.deepagent.workflow", "make_summarize_node"),
+    "make_grounding_eval_node": ("locus.deepagent.workflow", "make_grounding_eval_node"),
+    "make_regenerate_summary_node": ("locus.deepagent.workflow", "make_regenerate_summary_node"),
+    "make_replan_node": ("locus.deepagent.workflow", "make_replan_node"),
+    "route_after_grounding": ("locus.deepagent.workflow", "route_after_grounding"),
+    # Research workflow state keys
+    "KEY_PROMPT": ("locus.deepagent.workflow", "KEY_PROMPT"),
+    "KEY_EXECUTE_PROMPT": ("locus.deepagent.workflow", "KEY_EXECUTE_PROMPT"),
+    "KEY_EVIDENCE": ("locus.deepagent.workflow", "KEY_EVIDENCE"),
+    "KEY_GROUNDING_FACTS": ("locus.deepagent.workflow", "KEY_GROUNDING_FACTS"),
+    "KEY_CAUSAL_CHAIN": ("locus.deepagent.workflow", "KEY_CAUSAL_CHAIN"),
+    "KEY_CAUSAL_HYPOTHESIS": ("locus.deepagent.workflow", "KEY_CAUSAL_HYPOTHESIS"),
+    "KEY_CAUSAL_CONFIDENCE": ("locus.deepagent.workflow", "KEY_CAUSAL_CONFIDENCE"),
+    "KEY_SUMMARY": ("locus.deepagent.workflow", "KEY_SUMMARY"),
+    "KEY_STRUCTURED_OUTPUT": ("locus.deepagent.workflow", "KEY_STRUCTURED_OUTPUT"),
+    "KEY_GROUNDING_SCORE": ("locus.deepagent.workflow", "KEY_GROUNDING_SCORE"),
+    "KEY_UNGROUNDED_CLAIMS": ("locus.deepagent.workflow", "KEY_UNGROUNDED_CLAIMS"),
+    "KEY_REPLAN_COUNT": ("locus.deepagent.workflow", "KEY_REPLAN_COUNT"),
+    "KEY_REGENERATION_COUNT": ("locus.deepagent.workflow", "KEY_REGENERATION_COUNT"),
+    "KEY_STOP_REASON": ("locus.deepagent.workflow", "KEY_STOP_REASON"),
+    "KnowledgeProvider": ("locus.deepagent", "KnowledgeProvider"),
+    "KnowledgeRow": ("locus.deepagent", "KnowledgeRow"),
+    "ItemRef": ("locus.deepagent", "ItemRef"),
+    "Grounding": ("locus.deepagent", "Grounding"),
+}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for Agent and model classes."""
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        return getattr(module, attr_name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__version__ = "0.2.0"
+__all__ = [
+    "Agent",
+    "AgentConfig",
+    "AgentResult",
+    "AgentState",
+    "CausalChain",
+    "END",
+    "GraphConfig",
+    "GroundingEvaluator",
+    "GroundingEvent",
+    "Handoff",
+    "HandoffContext",
+    "HandoffReason",
+    "HookProvider",
+    "HookRegistry",
+    "LocusError",
+    "LocusEvent",
+    "LocusSettings",
+    "LoopAgent",
+    "Message",
+    "Orchestrator",
+    "ParallelPipeline",
+    "ReflectEvent",
+    "Reflector",
+    "Reflexion",
+    "Role",
+    "RoutingDecision",
+    "START",
+    "Send",
+    "SequentialPipeline",
+    "Specialist",
+    "StateGraph",
+    "TerminateEvent",
+    "ThinkEvent",
+    "ToolCall",
+    "ToolCompleteEvent",
+    "ToolContext",
+    "ToolStartEvent",
+    "__version__",
+    "create_handoff_agent",
+    "create_handoff_manager",
+    "create_orchestrator",
+    "tool",
+    # RAG (lazy)
+    "RAGRetriever",
+    "OCIEmbeddings",
+    "OracleVectorStore",
+    # PRISM router (lazy)
+    "Capability",
+    "CapabilityIndex",
+    "CognitiveCompiler",
+    "Complexity",
+    "GoalFrame",
+    "PolicyGate",
+    "PolicyVerdict",
+    "Protocol",
+    "ProtocolRegistry",
+    "Risk",
+    "Router",
+    "RunnableResult",
+    "SkillIndex",
+    "TaskType",
+    "builtin_protocols",
+    # Deep research — agent factory (lazy)
+    "create_deepagent",
+    "KnowledgeProvider",
+    "KnowledgeRow",
+    "ItemRef",
+    "Grounding",
+    # Deep research — research workflow primitives (lazy)
+    "create_research_workflow",
+    "make_execute_node",
+    "make_causal_inference_node",
+    "make_summarize_node",
+    "make_grounding_eval_node",
+    "make_regenerate_summary_node",
+    "make_replan_node",
+    "route_after_grounding",
+    # Research workflow state keys (lazy)
+    "KEY_PROMPT",
+    "KEY_EXECUTE_PROMPT",
+    "KEY_EVIDENCE",
+    "KEY_GROUNDING_FACTS",
+    "KEY_CAUSAL_CHAIN",
+    "KEY_CAUSAL_HYPOTHESIS",
+    "KEY_CAUSAL_CONFIDENCE",
+    "KEY_SUMMARY",
+    "KEY_STRUCTURED_OUTPUT",
+    "KEY_GROUNDING_SCORE",
+    "KEY_UNGROUNDED_CLAIMS",
+    "KEY_REPLAN_COUNT",
+    "KEY_REGENERATION_COUNT",
+    "KEY_STOP_REASON",
+]

locus/_oracle_pool_cache.py

@@ -0,0 +1,196 @@
+# Copyright (c) 2025, 2026 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v1.0 as shown at
+# https://oss.oracle.com/licenses/upl/
+
+"""Per-event-loop ``oracledb`` async pool cache.
+
+``oracledb`` async pools are bound to the asyncio event loop that
+creates them. The moment a caller invokes :meth:`Agent.run_sync` a
+second time (each call spins a fresh loop via :func:`asyncio.run`),
+or FastAPI's lifespan / anyio's BlockingPortal opens a different
+loop, the cached pool is attached to a dead loop and the next
+``acquire`` raises::
+
+    RuntimeError: Task ... got Future attached to a different loop
+
+The fix is to detect a loop mismatch and rebuild. This helper does
+that for every Oracle-touching backend in locus so the per-class
+copies stay one line.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any, Protocol
+
+
+class _PoolHolder(Protocol):
+    """Duck-typed surface every Oracle backend already exposes.
+
+    ``_pool`` is the cached pool; ``_pool_loop`` is the event loop it
+    was created on. Backends declare these as instance attributes (or
+    Pydantic private attrs) and call :func:`get_pool` to read /
+    refresh.
+    """
+
+    _pool: Any
+    _pool_loop: Any
+
+
+async def get_pool(
+    holder: _PoolHolder,
+    builder: Callable[[], Any] | Callable[[], Awaitable[Any]],
+) -> Any:
+    """Return a pool bound to the current event loop, building if needed.
+
+    Args:
+        holder: any object with mutable ``_pool`` / ``_pool_loop``
+            attributes. Most locus backends already satisfy this.
+        builder: zero-arg callable that produces a fresh
+            ``oracledb`` async pool. May be sync (the common case —
+            ``oracledb.create_pool_async`` returns the pool directly,
+            not a coroutine) or async.
+
+    The cached pool is invalidated when the running loop changes;
+    the dropped pool is left for ``oracledb`` to GC.
+    """
+    try:
+        running = asyncio.get_running_loop()
+    except RuntimeError:  # pragma: no cover — backend methods are async
+        running = None
+
+    if holder._pool is not None and holder._pool_loop is not running:
+        # Cross-loop call — drop the dead reference, reinitialise table
+        # provisioning state, and rebuild below.
+        holder._pool = None
+        # ``_initialized`` is a sibling flag on most backends that gates
+        # CREATE TABLE checks; reset it so the new pool re-verifies
+        # against the database.
+        if hasattr(holder, "_initialized"):
+            holder._initialized = False
+
+    if holder._pool is None:
+        pool = builder()
+        if asyncio.iscoroutine(pool):
+            pool = await pool
+        holder._pool = pool
+        holder._pool_loop = running
+
+    return holder._pool
+
+
+# Oracle network-layer errors that mean the underlying TCP connection
+# is dead — Autonomous Database aggressively closes idle sockets, and
+# the pool's cached connections may have been killed since the last
+# use. The fix is the same in every case: drop the pool, rebuild on the
+# next call, and retry the operation once.
+_RECONNECT_PREFIXES: tuple[str, ...] = (
+    "DPY-4011",  # the database or network closed the connection
+    "DPY-1001",  # not connected to the database
+    "DPY-6000",  # cannot connect to database (broken connection)
+    "ORA-12537",  # TNS:connection closed
+    "ORA-03113",  # end-of-file on communication channel
+    "ORA-03114",  # not connected to ORACLE
+    "ORA-03138",  # connection terminated due to security policy violation
+    "ORA-03146",  # invalid buffer length for TTC field (protocol desync)
+    "ORA-12541",  # TNS:no listener
+    "ORA-12170",  # TNS:Connect timeout occurred
+)
+
+
+def is_reconnectable(exc: BaseException) -> bool:
+    """True when *exc* names a network-layer disconnect we can recover from.
+
+    Matches against the error string rather than the exception class
+    because ``oracledb.DatabaseError`` wraps every database-side
+    condition; the ORA / DPY prefix tells reconnectable apart from
+    application-level errors (ORA-00001 etc.) we should not retry.
+    """
+    msg = str(exc)
+    return any(p in msg for p in _RECONNECT_PREFIXES)
+
+
+async def with_reconnect(
+    holder: _PoolHolder,
+    op: Callable[[Any], Awaitable[Any]],
+    builder: Callable[[], Any] | Callable[[], Awaitable[Any]],
+) -> Any:
+    """Run *op(pool)* with a one-shot rebuild on a network-layer error.
+
+    The retry path drops the pool and any sibling ``_initialized`` flag
+    so the second attempt walks the full provisioning path again. We
+    retry exactly once — a persistent disconnect (DB shutdown, wrong
+    DSN) should surface to the caller rather than loop.
+    """
+    pool = await get_pool(holder, builder)
+    try:
+        return await op(pool)
+    except BaseException as exc:  # noqa: BLE001
+        if not is_reconnectable(exc):
+            raise
+        # Drop the dead pool + sibling provisioning state so the next
+        # ``get_pool`` rebuilds cleanly. Don't await ``pool.close()`` —
+        # the broken socket would just raise again.
+        holder._pool = None
+        if hasattr(holder, "_initialized"):
+            holder._initialized = False
+        pool = await get_pool(holder, builder)
+        return await op(pool)
+
+
+@contextlib.asynccontextmanager
+async def safe_acquire(holder: _PoolHolder, pool: Any) -> AsyncIterator[Any]:
+    """Drop-in replacement for ``async with pool.acquire() as conn``.
+
+    Behaves like ``pool.acquire()`` for the body of the block — yields a
+    connection, no surprises. The wrapper exists for the *close* side:
+    Autonomous Database aggressively closes idle TCP connections, so a
+    pooled connection's socket may be dead by the time we're done with
+    it. When that close-time handshake fails with DPY-4011 (or a sibling
+    network-layer error) we:
+
+    1. Swallow the exception — the work inside the block already
+       committed, surfacing a close-time disconnect would mask a
+       successful save with a false error.
+    2. Invalidate the pool by setting ``holder._pool = None`` so the
+       next operation rebuilds it. Stale connections in the pool
+       likely share the same fate.
+
+    Errors raised *inside* the block propagate untouched — pair with
+    :func:`with_reconnect` if you also need body-time retry.
+
+    Implementation note: ``pool.acquire()`` in ``oracledb`` returns the
+    connection object directly (synchronously) and the connection
+    itself implements the async context-manager protocol. We drive
+    ``__aenter__`` / ``__aexit__`` manually so close-time errors can
+    be caught separately from body errors.
+    """
+    ctx = pool.acquire()
+    conn = await ctx.__aenter__()
+    body_exc: BaseException | None = None
+    try:
+        yield conn
+    except BaseException as exc:
+        body_exc = exc
+        raise
+    finally:
+        try:
+            if body_exc is None:
+                await ctx.__aexit__(None, None, None)
+            else:
+                await ctx.__aexit__(type(body_exc), body_exc, body_exc.__traceback__)
+        except BaseException as close_exc:  # noqa: BLE001
+            if is_reconnectable(close_exc):
+                # Socket's dead — drop the pool so the next call rebuilds.
+                # Suppress the close-time error: the body either succeeded
+                # already (no point surfacing a false failure) or has its
+                # own ``body_exc`` that's about to propagate.
+                holder._pool = None
+                if hasattr(holder, "_initialized"):
+                    holder._initialized = False
+            elif body_exc is None:
+                # Real close-time failure with no body error to propagate.
+                raise
+            # else: body_exc is about to propagate; don't mask it.

locus/_sync.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2025, 2026 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v1.0 as shown at
+# https://oss.oracle.com/licenses/upl/
+
+"""Run an async coroutine from sync code, regardless of loop state.
+
+Single shared helper used by every ``Sync*`` wrapper class shipped
+alongside the async Oracle primitives (checkpointer / store / vector
+store / loader / chunker / embedder). Mirrors the same trick
+``langgraph-oracledb``'s ``OracleSaver`` uses to bridge sync callers
+into an asyncpg-style driver — without taking any langchain or
+langgraph dependency.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Coroutine
+from typing import Any, TypeVar
+
+
+T = TypeVar("T")
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Drive a coroutine to completion from synchronous context.
+
+    Handles two cases:
+
+      1. **No running loop** (script / Jupyter cell with ``await``
+         disabled): use :func:`asyncio.run`.
+      2. **Inside a running loop** (Jupyter ``await``, FastAPI
+         handler, etc.): we can't reuse the active loop — instead we
+         run the coroutine to completion on a *fresh* event loop
+         hosted on a background thread, and block the calling thread
+         until that completes.
+
+    This is the same trick ``langgraph-oracledb``'s ``OracleSaver``
+    uses to bridge sync callers into an asyncpg-style driver.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop in this thread — safe to spin one up.
+        return asyncio.run(coro)
+
+    import threading
+
+    result: list[Any] = []
+    error: list[BaseException] = []
+
+    def runner() -> None:
+        new_loop = asyncio.new_event_loop()
+        try:
+            result.append(new_loop.run_until_complete(coro))
+        except BaseException as exc:  # noqa: BLE001 — re-raised in caller thread
+            error.append(exc)
+        finally:
+            new_loop.close()
+
+    t = threading.Thread(target=runner, daemon=True)
+    t.start()
+    t.join()
+    if error:
+        raise error[0]
+    return result[0]  # type: ignore[no-any-return]
+
+
+async def drain(agen: AsyncIterator[T]) -> list[T]:
+    """Drain an async iterator into a list.
+
+    Tiny helper used by every sync wrapper that needs to surface an
+    async generator as a plain ``list[...]`` to its synchronous
+    caller. Kept here so each wrapper module doesn't redefine it.
+    """
+    return [x async for x in agen]

locus/a2a/__init__.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2025, 2026 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v1.0 as shown at
+# https://oss.oracle.com/licenses/upl/
+
+"""Agent-to-Agent (A2A) protocol — spec-compliant cross-framework interop.
+
+Implements the public A2A protocol (https://a2aproject.github.io/A2A/)
+so Locus agents can talk to peers from other frameworks (Strands, ADK,
+Google A2A SDKs) without a translation shim.
+
+Wire surface served by :class:`A2AServer`:
+
+- ``GET  /.well-known/agent-card.json`` — public Agent Card (spec §5.5)
+- ``POST /``                            — JSON-RPC 2.0 method dispatch
+  for A2A v1.0 methods (``SendMessage``, ``SendStreamingMessage``,
+  ``GetTask``, ``ListTasks``, ``CancelTask``, ``SubscribeToTask``)
+  and compatibility methods (``message/send``, ``message/stream``,
+  ``tasks/get``, ``tasks/cancel``)
+- Backwards-compat: ``GET /agent-card``, ``POST /a2a/{invoke,stream}``
+
+Re-exports the spec models so consumers can do ``from locus.a2a import
+AgentCard, AgentSkill, Message, TextPart, Task`` directly. The
+``A2AV1*`` types are the canonical A2A v1.0 wire models and are stable
+public API for cross-framework interoperability.
+"""
+
+from locus.a2a.protocol import (
+    A2AClient,
+    A2AMessage,
+    A2ARequest,
+    A2AResponse,
+    A2AServer,
+)
+from locus.a2a.spec import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentProvider,
+    AgentSkill,
+    Artifact,
+    DataPart,
+    FilePart,
+    FileWithBytes,
+    FileWithUri,
+    JsonRpcError,
+    JsonRpcErrorResponse,
+    JsonRpcRequest,
+    JsonRpcSuccessResponse,
+    Message,
+    MessageSendConfiguration,
+    MessageSendParams,
+    Part,
+    PushNotificationAuthenticationInfo,
+    PushNotificationConfig,
+    Task,
+    TaskArtifactUpdateEvent,
+    TaskIdParams,
+    TaskPushNotificationConfig,
+    TaskQueryParams,
+    TaskState,
+    TaskStatus,
+    TaskStatusUpdateEvent,
+    TextPart,
+)
+from locus.a2a.spec_v1 import (
+    A2A_V1_PROTOCOL_VERSION,
+    A2AV1Artifact,
+    A2AV1CancelTaskRequest,
+    A2AV1GetTaskRequest,
+    A2AV1ListTasksRequest,
+    A2AV1ListTasksResponse,
+    A2AV1Message,
+    A2AV1Part,
+    A2AV1Role,
+    A2AV1SendMessageConfiguration,
+    A2AV1SendMessageRequest,
+    A2AV1SendMessageResponse,
+    A2AV1StreamResponse,
+    A2AV1Task,
+    A2AV1TaskArtifactUpdateEvent,
+    A2AV1TaskState,
+    A2AV1TaskStatus,
+    A2AV1TaskStatusUpdateEvent,
+)
+
+
+__all__ = [
+    "A2A_V1_PROTOCOL_VERSION",
+    "A2AV1Artifact",
+    "A2AV1CancelTaskRequest",
+    "A2AV1GetTaskRequest",
+    "A2AV1ListTasksRequest",
+    "A2AV1ListTasksResponse",
+    "A2AV1Message",
+    "A2AV1Part",
+    "A2AV1Role",
+    "A2AV1SendMessageConfiguration",
+    "A2AV1SendMessageRequest",
+    "A2AV1SendMessageResponse",
+    "A2AV1StreamResponse",
+    "A2AV1Task",
+    "A2AV1TaskArtifactUpdateEvent",
+    "A2AV1TaskState",
+    "A2AV1TaskStatus",
+    "A2AV1TaskStatusUpdateEvent",
+    # Server / client.
+    "A2AClient",
+    "A2AServer",
+    # Spec models.
+    "AgentCapabilities",
+    "AgentCard",
+    "AgentInterface",
+    "AgentProvider",
+    "AgentSkill",
+    "Artifact",
+    "DataPart",
+    "FilePart",
+    "FileWithBytes",
+    "FileWithUri",
+    "JsonRpcError",
+    "JsonRpcErrorResponse",
+    "JsonRpcRequest",
+    "JsonRpcSuccessResponse",
+    "Message",
+    "MessageSendConfiguration",
+    "MessageSendParams",
+    "Part",
+    "PushNotificationAuthenticationInfo",
+    "PushNotificationConfig",
+    "Task",
+    "TaskArtifactUpdateEvent",
+    "TaskIdParams",
+    "TaskPushNotificationConfig",
+    "TaskQueryParams",
+    "TaskState",
+    "TaskStatus",
+    "TaskStatusUpdateEvent",
+    "TextPart",
+    # Legacy flat models (kept for the pre-spec wire surface).
+    "A2AMessage",
+    "A2ARequest",
+    "A2AResponse",
+]