acp-sdk 0.0.6__py3-none-any.whl → 0.1.0__py3-none-any.whl

acp_sdk/__init__.py

@@ -0,0 +1,2 @@
+from acp_sdk.models import *  # noqa: F403
+from acp_sdk.version import __version__ as __version__

acp_sdk/client/__init__.py

@@ -0,0 +1 @@
+from acp_sdk.client.client import Client as Client

acp_sdk/client/client.py

@@ -0,0 +1,178 @@
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Self
+
+import httpx
+from httpx_sse import EventSource, aconnect_sse
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from pydantic import TypeAdapter
+
+from acp_sdk.models import (
+    ACPError,
+    Agent,
+    AgentName,
+    AgentReadResponse,
+    AgentsListResponse,
+    AwaitResume,
+    CreatedEvent,
+    Error,
+    Message,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunEvent,
+    RunId,
+    RunMode,
+    RunResumeRequest,
+    RunResumeResponse,
+    SessionId,
+)
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        base_url: httpx.URL | str = "",
+        session_id: SessionId | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self.session_id = session_id
+
+        self._client = self._init_client(client)
+
+    def _init_client(self, client: httpx.AsyncClient | None = None) -> httpx.AsyncClient:
+        client = client or httpx.AsyncClient(base_url=self.base_url)
+        HTTPXClientInstrumentor.instrument_client(client)
+        return client
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        await self._client.__aexit__(exc_type, exc_value, traceback)
+
+    @asynccontextmanager
+    async def session(self, session_id: SessionId | None = None) -> AsyncGenerator[Self]:
+        yield Client(client=self._client, session_id=session_id or uuid.uuid4())
+
+    async def agents(self) -> AsyncIterator[Agent]:
+        response = await self._client.get("/agents")
+        self._raise_error(response)
+        for agent in AgentsListResponse.model_validate(response.json()).agents:
+            yield agent
+
+    async def agent(self, *, name: AgentName) -> Agent:
+        response = await self._client.get(f"/agents/{name}")
+        self._raise_error(response)
+        return AgentReadResponse.model_validate(response.json())
+
+    async def run_sync(self, *, agent: AgentName, inputs: list[Message]) -> Run:
+        response = await self._client.post(
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.SYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
+
+    async def run_async(self, *, agent: AgentName, inputs: list[Message]) -> Run:
+        response = await self._client.post(
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.ASYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
+
+    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[RunEvent]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.STREAM,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                if isinstance(event, CreatedEvent):
+                    self._set_session(event.run)
+                yield event
+
+    async def run_status(self, *, run_id: RunId) -> Run:
+        response = await self._client.get(f"/runs/{run_id}")
+        self._raise_error(response)
+        return Run.model_validate(response.json())
+
+    async def run_cancel(self, *, run_id: RunId) -> Run:
+        response = await self._client.post(f"/runs/{run_id}/cancel")
+        self._raise_error(response)
+        return RunCancelResponse.model_validate(response.json())
+
+    async def run_resume_sync(self, *, run_id: RunId, await_: AwaitResume) -> Run:
+        response = await self._client.post(
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.SYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunResumeResponse.model_validate(response.json())
+
+    async def run_resume_async(self, *, run_id: RunId, await_: AwaitResume) -> Run:
+        response = await self._client.post(
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.ASYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunResumeResponse.model_validate(response.json())
+
+    async def run_resume_stream(self, *, run_id: RunId, await_: AwaitResume) -> AsyncIterator[RunEvent]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.STREAM).model_dump(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                yield event
+
+    async def _validate_stream(
+        self,
+        event_source: EventSource,
+    ) -> AsyncIterator[RunEvent]:
+        async for event in event_source.aiter_sse():
+            event = TypeAdapter(RunEvent).validate_json(event.data)
+            yield event
+
+    def _raise_error(self, response: httpx.Response) -> None:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPError:
+            raise ACPError(Error.model_validate(response.json()))
+
+    def _set_session(self, run: Run) -> None:
+        self.session_id = run.session_id

acp_sdk/models/__init__.py

@@ -0,0 +1,3 @@
+from acp_sdk.models.errors import *  # noqa: F403
+from acp_sdk.models.models import *  # noqa: F403
+from acp_sdk.models.schemas import *  # noqa: F403

acp_sdk/models/errors.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ErrorCode(str, Enum):
+    SERVER_ERROR = "server_error"
+    INVALID_INPUT = "invalid_input"
+    NOT_FOUND = "not_found"
+
+
+class Error(BaseModel):
+    code: ErrorCode
+    message: str
+
+
+class ACPError(Exception):
+    def __init__(self, error: Error) -> None:
+        super().__init__()
+        self.error = error
+
+    def __str__(self) -> str:
+        return str(self.error.message)

acp_sdk/models/models.py

@@ -0,0 +1,192 @@
+import uuid
+from enum import Enum
+from typing import Any, Literal, Optional, Union
+
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field
+
+from acp_sdk.models.errors import Error
+
+
+class Metadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class AnyModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class MessagePart(BaseModel):
+    name: Optional[str] = None
+    content_type: str
+    content: Optional[str] = None
+    content_encoding: Optional[Literal["plain", "base64"]] = "plain"
+    content_url: Optional[AnyUrl] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.content is None and self.content_url is None:
+            raise ValueError("Either content or content_url must be provided")
+        if self.content is not None and self.content_url is not None:
+            raise ValueError("Only one of content or content_url can be provided")
+
+
+class Message(BaseModel):
+    parts: list[MessagePart]
+
+    def __add__(self, other: "Message") -> "Message":
+        if not isinstance(other, Message):
+            raise TypeError(f"Cannot concatenate Message with {type(other).__name__}")
+        return Message(*(self.parts + other.parts))
+
+    def __str__(self) -> str:
+        return "".join(
+            part.content for part in self.parts if part.content is not None and part.content_type == "text/plain"
+        )
+
+
+AgentName = str
+SessionId = uuid.UUID
+RunId = uuid.UUID
+
+
+class RunMode(str, Enum):
+    SYNC = "sync"
+    ASYNC = "async"
+    STREAM = "stream"
+
+
+class RunStatus(str, Enum):
+    CREATED = "created"
+    IN_PROGRESS = "in-progress"
+    AWAITING = "awaiting"
+    CANCELLING = "cancelling"
+    CANCELLED = "cancelled"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+    @property
+    def is_terminal(self) -> bool:
+        terminal_states = {RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED}
+        return self in terminal_states
+
+
+class Await(BaseModel):
+    type: Literal["placeholder"] = "placeholder"
+
+
+class AwaitResume(BaseModel):
+    pass
+
+
+class Artifact(BaseModel):
+    name: str
+    content_type: str
+    content: Optional[str] = None
+    content_encoding: Optional[Literal["plain", "base64"]] = "plain"
+    content_url: Optional[AnyUrl] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.content is None and self.content_url is None:
+            raise ValueError("Either content or content_url must be provided")
+        if self.content is not None and self.content_url is not None:
+            raise ValueError("Only one of content or content_url can be provided")
+
+
+class Run(BaseModel):
+    run_id: RunId = Field(default_factory=uuid.uuid4)
+    agent_name: AgentName
+    session_id: SessionId | None = None
+    status: RunStatus = RunStatus.CREATED
+    await_: Await | None = Field(None, alias="await")
+    outputs: list[Message] = []
+    artifacts: list[Artifact] = []
+    error: Error | None = None
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def model_dump_json(
+        self,
+        **kwargs: dict[str, Any],
+    ) -> str:
+        return super().model_dump_json(
+            by_alias=True,
+            **kwargs,
+        )
+
+
+class MessageEvent(BaseModel):
+    type: Literal["message"] = "message"
+    message: Message
+
+
+class ArtifactEvent(BaseModel):
+    type: Literal["artifact"] = "artifact"
+    artifact: Artifact
+
+
+class AwaitEvent(BaseModel):
+    type: Literal["await"] = "await"
+    await_: Await | None = Field(alias="await")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def model_dump_json(
+        self,
+        **kwargs: dict[str, Any],
+    ) -> str:
+        return super().model_dump_json(
+            by_alias=True,
+            **kwargs,
+        )
+
+
+class GenericEvent(BaseModel):
+    type: Literal["generic"] = "generic"
+    generic: AnyModel
+
+
+class CreatedEvent(BaseModel):
+    type: Literal["created"] = "created"
+    run: Run
+
+
+class InProgressEvent(BaseModel):
+    type: Literal["in-progress"] = "in-progress"
+    run: Run
+
+
+class FailedEvent(BaseModel):
+    type: Literal["failed"] = "failed"
+    run: Run
+
+
+class CancelledEvent(BaseModel):
+    type: Literal["cancelled"] = "cancelled"
+    run: Run
+
+
+class CompletedEvent(BaseModel):
+    type: Literal["completed"] = "completed"
+    run: Run
+
+
+RunEvent = Union[
+    CreatedEvent,
+    InProgressEvent,
+    MessageEvent,
+    AwaitEvent,
+    GenericEvent,
+    CancelledEvent,
+    FailedEvent,
+    CompletedEvent,
+    ArtifactEvent,
+]
+
+
+class Agent(BaseModel):
+    name: str
+    description: str | None = None
+    metadata: Metadata = Metadata()

acp_sdk/models/schemas.py

@@ -0,0 +1,41 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from acp_sdk.models.models import Agent, AgentName, AwaitResume, Message, Run, RunMode, SessionId
+
+
+class AgentsListResponse(BaseModel):
+    agents: list[Agent]
+
+
+class AgentReadResponse(Agent):
+    pass
+
+
+class RunCreateRequest(BaseModel):
+    agent_name: AgentName
+    session_id: SessionId | None = None
+    inputs: list[Message]
+    mode: RunMode = RunMode.SYNC
+
+
+class RunCreateResponse(Run):
+    pass
+
+
+class RunResumeRequest(BaseModel):
+    await_: AwaitResume = Field(alias="await")
+    mode: RunMode
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class RunResumeResponse(Run):
+    pass
+
+
+class RunReadResponse(Run):
+    pass
+
+
+class RunCancelResponse(Run):
+    pass

acp_sdk/server/__init__.py

@@ -0,0 +1,7 @@
+from acp_sdk.server.agent import Agent as Agent
+from acp_sdk.server.agent import agent as agent
+from acp_sdk.server.app import create_app as create_app
+from acp_sdk.server.context import Context as Context
+from acp_sdk.server.server import Server as Server
+from acp_sdk.server.types import RunYield as RunYield
+from acp_sdk.server.types import RunYieldResume as RunYieldResume

acp_sdk/server/agent.py

@@ -0,0 +1,178 @@
+import abc
+import asyncio
+import inspect
+from collections.abc import AsyncGenerator, Coroutine, Generator
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
+
+import janus
+
+from acp_sdk.models import (
+    AgentName,
+    Message,
+    SessionId,
+)
+from acp_sdk.models.models import Metadata
+from acp_sdk.server.context import Context
+from acp_sdk.server.types import RunYield, RunYieldResume
+
+
+class Agent(abc.ABC):
+    @property
+    def name(self) -> AgentName:
+        return self.__class__.__name__
+
+    @property
+    def description(self) -> str:
+        return ""
+
+    @property
+    def metadata(self) -> Metadata:
+        return Metadata()
+
+    @abc.abstractmethod
+    def run(
+        self, inputs: list[Message], context: Context
+    ) -> (
+        AsyncGenerator[RunYield, RunYieldResume] | Generator[RunYield, RunYieldResume] | Coroutine[RunYield] | RunYield
+    ):
+        pass
+
+    async def execute(
+        self, inputs: list[Message], session_id: SessionId | None, executor: ThreadPoolExecutor
+    ) -> AsyncGenerator[RunYield, RunYieldResume]:
+        yield_queue: janus.Queue[RunYield] = janus.Queue()
+        yield_resume_queue: janus.Queue[RunYieldResume] = janus.Queue()
+
+        context = Context(
+            session_id=session_id, executor=executor, yield_queue=yield_queue, yield_resume_queue=yield_resume_queue
+        )
+
+        if inspect.isasyncgenfunction(self.run):
+            run = asyncio.create_task(self._run_async_gen(inputs, context))
+        elif inspect.iscoroutinefunction(self.run):
+            run = asyncio.create_task(self._run_coro(inputs, context))
+        elif inspect.isgeneratorfunction(self.run):
+            run = asyncio.get_running_loop().run_in_executor(executor, self._run_gen, inputs, context)
+        else:
+            run = asyncio.get_running_loop().run_in_executor(executor, self._run_func, inputs, context)
+
+        try:
+            while True:
+                value = yield await yield_queue.async_q.get()
+                await yield_resume_queue.async_q.put(value)
+        except janus.AsyncQueueShutDown:
+            pass
+        finally:
+            await run  # Raise exceptions
+
+    async def _run_async_gen(self, input: Message, context: Context) -> None:
+        try:
+            gen: AsyncGenerator[RunYield, RunYieldResume] = self.run(input, context)
+            value = None
+            while True:
+                value = await context.yield_async(await gen.asend(value))
+        except StopAsyncIteration:
+            pass
+        finally:
+            context.shutdown()
+
+    async def _run_coro(self, input: Message, context: Context) -> None:
+        try:
+            await context.yield_async(await self.run(input, context))
+        finally:
+            context.shutdown()
+
+    def _run_gen(self, input: Message, context: Context) -> None:
+        try:
+            gen: Generator[RunYield, RunYieldResume] = self.run(input, context)
+            value = None
+            while True:
+                value = context.yield_sync(gen.send(value))
+        except StopIteration:
+            pass
+        finally:
+            context.shutdown()
+
+    def _run_func(self, input: Message, context: Context) -> None:
+        try:
+            context.yield_sync(self.run(input, context))
+        finally:
+            context.shutdown()
+
+
+def agent(
+    name: str | None = None,
+    description: str | None = None,
+    *,
+    metadata: Metadata | None = None,
+) -> Callable[[Callable], Agent]:
+    """Decorator to create an agent."""
+
+    def decorator(fn: Callable) -> Agent:
+        signature = inspect.signature(fn)
+        parameters = list(signature.parameters.values())
+
+        if len(parameters) == 0:
+            raise TypeError("The agent function must have at least 'input' argument")
+        if len(parameters) > 2:
+            raise TypeError("The agent function must have only 'input' and 'context' arguments")
+        if len(parameters) == 2 and parameters[1].name != "context":
+            raise TypeError("The second argument of the agent function must be 'context'")
+
+        has_context_param = len(parameters) == 2
+
+        class DecoratorAgentBase(Agent):
+            @property
+            def name(self) -> str:
+                return name or fn.__name__
+
+            @property
+            def description(self) -> str:
+                return description or fn.__doc__ or ""
+
+            @property
+            def metadata(self) -> Metadata:
+                return metadata or Metadata()
+
+        agent: Agent
+        if inspect.isasyncgenfunction(fn):
+
+            class AsyncGenDecoratorAgent(DecoratorAgentBase):
+                async def run(self, input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+                    try:
+                        gen: AsyncGenerator[RunYield, RunYieldResume] = (
+                            fn(input, context) if has_context_param else fn(input)
+                        )
+                        value = None
+                        while True:
+                            value = yield await gen.asend(value)
+                    except StopAsyncIteration:
+                        pass
+
+            agent = AsyncGenDecoratorAgent()
+        elif inspect.iscoroutinefunction(fn):
+
+            class CoroDecoratorAgent(DecoratorAgentBase):
+                async def run(self, input: Message, context: Context) -> Coroutine[RunYield]:
+                    return await (fn(input, context) if has_context_param else fn(input))
+
+            agent = CoroDecoratorAgent()
+        elif inspect.isgeneratorfunction(fn):
+
+            class GenDecoratorAgent(DecoratorAgentBase):
+                def run(self, input: Message, context: Context) -> Generator[RunYield, RunYieldResume]:
+                    yield from (fn(input, context) if has_context_param else fn(input))
+
+            agent = GenDecoratorAgent()
+        else:
+
+            class FuncDecoratorAgent(DecoratorAgentBase):
+                def run(self, input: Message, context: Context) -> RunYield:
+                    return fn(input, context) if has_context_param else fn(input)
+
+            agent = FuncDecoratorAgent()
+
+        return agent
+
+    return decorator