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

acp_sdk/server/app.py

@@ -0,0 +1,176 @@
+from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+from enum import Enum
+
+from fastapi import FastAPI, HTTPException, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse, StreamingResponse
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+from acp_sdk.models import (
+    Agent as AgentModel,
+)
+from acp_sdk.models import (
+    AgentName,
+    AgentReadResponse,
+    AgentsListResponse,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunId,
+    RunMode,
+    RunReadResponse,
+    RunResumeRequest,
+    RunResumeResponse,
+    SessionId,
+)
+from acp_sdk.models.errors import ACPError
+from acp_sdk.server.agent import Agent
+from acp_sdk.server.bundle import RunBundle
+from acp_sdk.server.errors import (
+    RequestValidationError,
+    StarletteHTTPException,
+    acp_error_handler,
+    catch_all_exception_handler,
+    http_exception_handler,
+    validation_exception_handler,
+)
+from acp_sdk.server.session import Session
+from acp_sdk.server.utils import stream_sse
+
+
+class Headers(str, Enum):
+    RUN_ID = "Run-ID"
+
+
+def create_app(*agents: Agent) -> FastAPI:
+    executor: ThreadPoolExecutor
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+        nonlocal executor
+        with ThreadPoolExecutor() as exec:
+            executor = exec
+            yield
+
+    app = FastAPI(lifespan=lifespan)
+
+    FastAPIInstrumentor.instrument_app(app)
+
+    agents: dict[AgentName, Agent] = {agent.name: agent for agent in agents}
+    runs: dict[RunId, RunBundle] = {}
+    sessions: dict[SessionId, Session] = {}
+
+    app.exception_handler(ACPError)(acp_error_handler)
+    app.exception_handler(StarletteHTTPException)(http_exception_handler)
+    app.exception_handler(RequestValidationError)(validation_exception_handler)
+    app.exception_handler(Exception)(catch_all_exception_handler)
+
+    def find_run_bundle(run_id: RunId) -> RunBundle:
+        bundle = runs.get(run_id)
+        if not bundle:
+            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+        return bundle
+
+    def find_agent(agent_name: AgentName) -> Agent:
+        agent = agents.get(agent_name, None)
+        if not agent:
+            raise HTTPException(status_code=404, detail=f"Agent {agent_name} not found")
+        return agent
+
+    @app.get("/agents")
+    async def list_agents() -> AgentsListResponse:
+        return AgentsListResponse(
+            agents=[
+                AgentModel(name=agent.name, description=agent.description, metadata=agent.metadata)
+                for agent in agents.values()
+            ]
+        )
+
+    @app.get("/agents/{name}")
+    async def read_agent(name: AgentName) -> AgentReadResponse:
+        agent = find_agent(name)
+        return AgentModel(name=agent.name, description=agent.description, metadata=agent.metadata)
+
+    @app.post("/runs")
+    async def create_run(request: RunCreateRequest) -> RunCreateResponse:
+        agent = find_agent(request.agent_name)
+
+        session = sessions.get(request.session_id, Session()) if request.session_id else Session()
+        nonlocal executor
+        bundle = RunBundle(
+            agent=agent,
+            run=Run(agent_name=agent.name, session_id=session.id),
+            inputs=request.inputs,
+            history=list(session.history()),
+            executor=executor,
+        )
+        session.append(bundle)
+
+        runs[bundle.run.run_id] = bundle
+        sessions[session.id] = session
+
+        headers = {Headers.RUN_ID: str(bundle.run.run_id)}
+
+        match request.mode:
+            case RunMode.STREAM:
+                return StreamingResponse(
+                    stream_sse(bundle),
+                    headers=headers,
+                    media_type="text/event-stream",
+                )
+            case RunMode.SYNC:
+                await bundle.join()
+                return JSONResponse(
+                    headers=headers,
+                    content=jsonable_encoder(bundle.run),
+                )
+            case RunMode.ASYNC:
+                return JSONResponse(
+                    status_code=status.HTTP_202_ACCEPTED,
+                    headers=headers,
+                    content=jsonable_encoder(bundle.run),
+                )
+            case _:
+                raise NotImplementedError()
+
+    @app.get("/runs/{run_id}")
+    async def read_run(run_id: RunId) -> RunReadResponse:
+        bundle = find_run_bundle(run_id)
+        return bundle.run
+
+    @app.post("/runs/{run_id}")
+    async def resume_run(run_id: RunId, request: RunResumeRequest) -> RunResumeResponse:
+        bundle = find_run_bundle(run_id)
+        await bundle.resume(request.await_)
+        match request.mode:
+            case RunMode.STREAM:
+                return StreamingResponse(
+                    stream_sse(bundle),
+                    media_type="text/event-stream",
+                )
+            case RunMode.SYNC:
+                await bundle.join()
+                return bundle.run
+            case RunMode.ASYNC:
+                return JSONResponse(
+                    status_code=status.HTTP_202_ACCEPTED,
+                    content=jsonable_encoder(bundle.run),
+                )
+            case _:
+                raise NotImplementedError()
+
+    @app.post("/runs/{run_id}/cancel")
+    async def cancel_run(run_id: RunId) -> RunCancelResponse:
+        bundle = find_run_bundle(run_id)
+        if bundle.run.status.is_terminal:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Run in terminal status {bundle.run.status} can't be cancelled",
+            )
+        await bundle.cancel()
+        return JSONResponse(status_code=status.HTTP_202_ACCEPTED, content=jsonable_encoder(bundle.run))
+
+    return app

acp_sdk/server/bundle.py

@@ -0,0 +1,146 @@
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
+
+from pydantic import ValidationError
+
+from acp_sdk.models import (
+    AnyModel,
+    Artifact,
+    ArtifactEvent,
+    Await,
+    AwaitEvent,
+    AwaitResume,
+    CancelledEvent,
+    CompletedEvent,
+    CreatedEvent,
+    Error,
+    FailedEvent,
+    GenericEvent,
+    InProgressEvent,
+    Message,
+    MessageEvent,
+    Run,
+    RunEvent,
+    RunStatus,
+)
+from acp_sdk.models.errors import ErrorCode
+from acp_sdk.server.agent import Agent
+from acp_sdk.server.logging import logger
+from acp_sdk.server.telemetry import get_tracer
+
+
+class RunBundle:
+    def __init__(
+        self, *, agent: Agent, run: Run, inputs: list[Message], history: list[Message], executor: ThreadPoolExecutor
+    ) -> None:
+        self.agent = agent
+        self.run = run
+        self.inputs = inputs
+        self.history = history
+
+        self.stream_queue: asyncio.Queue[RunEvent] = asyncio.Queue()
+
+        self.await_queue: asyncio.Queue[AwaitResume] = asyncio.Queue(maxsize=1)
+        self.await_or_terminate_event = asyncio.Event()
+
+        self.task = asyncio.create_task(self._execute(inputs, executor=executor))
+
+    async def stream(self) -> AsyncGenerator[RunEvent]:
+        while True:
+            event = await self.stream_queue.get()
+            if event is None:
+                break
+            yield event
+            self.stream_queue.task_done()
+
+    async def emit(self, event: RunEvent) -> None:
+        await self.stream_queue.put(event)
+
+    async def await_(self) -> AwaitResume:
+        await self.stream_queue.put(None)
+        self.await_queue.empty()
+        self.await_or_terminate_event.set()
+        self.await_or_terminate_event.clear()
+        resume = await self.await_queue.get()
+        self.await_queue.task_done()
+        return resume
+
+    async def resume(self, resume: AwaitResume) -> None:
+        self.stream_queue = asyncio.Queue()
+        await self.await_queue.put(resume)
+        self.run.status = RunStatus.IN_PROGRESS
+        self.run.await_ = None
+
+    async def cancel(self) -> None:
+        self.task.cancel()
+        self.run.status = RunStatus.CANCELLING
+        self.run.await_ = None
+
+    async def join(self) -> None:
+        await self.await_or_terminate_event.wait()
+
+    async def _execute(self, inputs: list[Message], *, executor: ThreadPoolExecutor) -> None:
+        with get_tracer().start_as_current_span("run"):
+            run_logger = logging.LoggerAdapter(logger, {"run_id": str(self.run.run_id)})
+
+            try:
+                await self.emit(CreatedEvent(run=self.run))
+
+                generator = self.agent.execute(
+                    inputs=self.history + inputs, session_id=self.run.session_id, executor=executor
+                )
+                run_logger.info("Run started")
+
+                self.run.status = RunStatus.IN_PROGRESS
+                await self.emit(InProgressEvent(run=self.run))
+
+                await_resume = None
+                while True:
+                    next = await generator.asend(await_resume)
+                    if isinstance(next, Message):
+                        self.run.outputs.append(next)
+                        await self.emit(MessageEvent(message=next))
+                    elif isinstance(next, Artifact):
+                        self.run.artifacts.append(next)
+                        await self.emit(ArtifactEvent(artifact=next))
+                    elif isinstance(next, Await):
+                        self.run.await_ = next
+                        self.run.status = RunStatus.AWAITING
+                        await self.emit(
+                            AwaitEvent.model_validate(
+                                {
+                                    "run_id": self.run.run_id,
+                                    "type": "await",
+                                    "await": next,
+                                }
+                            )
+                        )
+                        run_logger.info("Run awaited")
+                        await_resume = await self.await_()
+                        await self.emit(InProgressEvent(run=self.run))
+                        run_logger.info("Run resumed")
+                    else:
+                        try:
+                            generic = AnyModel.model_validate(next)
+                            await self.emit(GenericEvent(generic=generic))
+                        except ValidationError:
+                            raise TypeError("Invalid yield")
+            except StopAsyncIteration:
+                self.run.status = RunStatus.COMPLETED
+                await self.emit(CompletedEvent(run=self.run))
+                run_logger.info("Run completed")
+            except asyncio.CancelledError:
+                self.run.status = RunStatus.CANCELLED
+                await self.emit(CancelledEvent(run=self.run))
+                run_logger.info("Run cancelled")
+            except Exception as e:
+                self.run.error = Error(code=ErrorCode.SERVER_ERROR, message=str(e))
+                self.run.status = RunStatus.FAILED
+                await self.emit(FailedEvent(run=self.run))
+                run_logger.exception("Run failed")
+                raise
+            finally:
+                self.await_or_terminate_event.set()
+                await self.stream_queue.put(None)

acp_sdk/server/context.py

@@ -0,0 +1,33 @@
+from concurrent.futures import ThreadPoolExecutor
+
+import janus
+
+from acp_sdk.models import SessionId
+from acp_sdk.server.types import RunYield, RunYieldResume
+
+
+class Context:
+    def __init__(
+        self,
+        *,
+        session_id: SessionId | None = None,
+        executor: ThreadPoolExecutor,
+        yield_queue: janus.Queue[RunYield],
+        yield_resume_queue: janus.Queue[RunYieldResume],
+    ) -> None:
+        self.session_id = session_id
+        self.executor = executor
+        self._yield_queue = yield_queue
+        self._yield_resume_queue = yield_resume_queue
+
+    def yield_sync(self, value: RunYield) -> RunYieldResume:
+        self._yield_queue.sync_q.put(value)
+        return self._yield_resume_queue.sync_q.get()
+
+    async def yield_async(self, value: RunYield) -> RunYieldResume:
+        await self._yield_queue.async_q.put(value)
+        return await self._yield_resume_queue.async_q.get()
+
+    def shutdown(self) -> None:
+        self._yield_queue.shutdown()
+        self._yield_resume_queue.shutdown()

acp_sdk/server/errors.py

@@ -0,0 +1,54 @@
+from fastapi import Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from acp_sdk.models import Error, ErrorCode
+from acp_sdk.models.errors import ACPError
+from acp_sdk.server.logging import logger
+
+
+def error_code_to_status_code(error_code: ErrorCode) -> int:
+    match error_code:
+        case ErrorCode.NOT_FOUND:
+            return status.HTTP_404_NOT_FOUND
+        case ErrorCode.INVALID_INPUT:
+            return status.HTTP_422_UNPROCESSABLE_ENTITY
+        case _:
+            return status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+def status_code_to_error_code(status_code: int) -> ErrorCode:
+    match status_code:
+        case status.HTTP_400_BAD_REQUEST:
+            return ErrorCode.INVALID_INPUT
+        case status.HTTP_404_NOT_FOUND:
+            return ErrorCode.NOT_FOUND
+        case status.HTTP_422_UNPROCESSABLE_ENTITY:
+            return ErrorCode.INVALID_INPUT
+        case _:
+            return ErrorCode.SERVER_ERROR
+
+
+async def acp_error_handler(request: Request, exc: ACPError, *, status_code: int | None = None) -> JSONResponse:
+    error = exc.error
+    return JSONResponse(status_code=status_code or error_code_to_status_code(error.code), content=error.model_dump())
+
+
+async def http_exception_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+    return await acp_error_handler(
+        request,
+        ACPError(Error(code=status_code_to_error_code(exc.status_code), message=exc.detail)),
+        status_code=exc.status_code,
+    )
+
+
+async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return await acp_error_handler(request, ACPError(Error(code=ErrorCode.INVALID_INPUT, message=str(exc))))
+
+
+async def catch_all_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.error(exc)
+    return await acp_error_handler(
+        request, ACPError(Error(code=ErrorCode.SERVER_ERROR, message="An unexpected error occurred"))
+    )

acp_sdk/server/logging.py

@@ -0,0 +1,16 @@
+import logging
+
+from uvicorn.logging import DefaultFormatter
+
+logger = logging.getLogger("acp")
+
+
+def configure_logger() -> None:
+    """Utility that configures the root logger"""
+    root_logger = logging.getLogger()
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(DefaultFormatter(fmt="%(levelprefix)s %(message)s"))
+
+    root_logger.addHandler(handler)
+    root_logger.setLevel(logging.INFO)

acp_sdk/server/server.py

@@ -0,0 +1,166 @@
+import asyncio
+import os
+from collections.abc import Awaitable
+from typing import Any, Callable
+
+import uvicorn
+import uvicorn.config
+
+from acp_sdk.models import Metadata
+from acp_sdk.server.agent import Agent
+from acp_sdk.server.agent import agent as agent_decorator
+from acp_sdk.server.app import create_app
+from acp_sdk.server.logging import configure_logger as configure_logger_func
+from acp_sdk.server.telemetry import configure_telemetry as configure_telemetry_func
+
+
+class Server:
+    def __init__(self) -> None:
+        self._agents: list[Agent] = []
+        self._server: uvicorn.Server | None = None
+
+    def agent(
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        *,
+        metadata: Metadata | None = None,
+    ) -> Callable:
+        """Decorator to register an agent."""
+
+        def decorator(fn: Callable) -> Callable:
+            agent = agent_decorator(name=name, description=description, metadata=metadata)(fn)
+            self.register(agent)
+            return fn
+
+        return decorator
+
+    def register(self, *agents: Agent) -> None:
+        self._agents.extend(agents)
+
+    def run(
+        self,
+        configure_logger: bool = True,
+        configure_telemetry: bool = False,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        uds: str | None = None,
+        fd: int | None = None,
+        loop: uvicorn.config.LoopSetupType = "auto",
+        http: type[asyncio.Protocol] | uvicorn.config.HTTPProtocolType = "auto",
+        ws: type[asyncio.Protocol] | uvicorn.config.WSProtocolType = "auto",
+        ws_max_size: int = 16 * 1024 * 1024,
+        ws_max_queue: int = 32,
+        ws_ping_interval: float | None = 20.0,
+        ws_ping_timeout: float | None = 20.0,
+        ws_per_message_deflate: bool = True,
+        lifespan: uvicorn.config.LifespanType = "auto",
+        env_file: str | os.PathLike[str] | None = None,
+        log_config: dict[str, Any]
+        | str
+        | uvicorn.config.RawConfigParser
+        | uvicorn.config.IO[Any]
+        | None = uvicorn.config.LOGGING_CONFIG,
+        log_level: str | int | None = None,
+        access_log: bool = True,
+        use_colors: bool | None = None,
+        interface: uvicorn.config.InterfaceType = "auto",
+        reload: bool = False,
+        reload_dirs: list[str] | str | None = None,
+        reload_delay: float = 0.25,
+        reload_includes: list[str] | str | None = None,
+        reload_excludes: list[str] | str | None = None,
+        workers: int | None = None,
+        proxy_headers: bool = True,
+        server_header: bool = True,
+        date_header: bool = True,
+        forwarded_allow_ips: list[str] | str | None = None,
+        root_path: str = "",
+        limit_concurrency: int | None = None,
+        limit_max_requests: int | None = None,
+        backlog: int = 2048,
+        timeout_keep_alive: int = 5,
+        timeout_notify: int = 30,
+        timeout_graceful_shutdown: int | None = None,
+        callback_notify: Callable[..., Awaitable[None]] | None = None,
+        ssl_keyfile: str | os.PathLike[str] | None = None,
+        ssl_certfile: str | os.PathLike[str] | None = None,
+        ssl_keyfile_password: str | None = None,
+        ssl_version: int = uvicorn.config.SSL_PROTOCOL_VERSION,
+        ssl_cert_reqs: int = uvicorn.config.ssl.CERT_NONE,
+        ssl_ca_certs: str | None = None,
+        ssl_ciphers: str = "TLSv1",
+        headers: list[tuple[str, str]] | None = None,
+        factory: bool = False,
+        h11_max_incomplete_event_size: int | None = None,
+    ) -> None:
+        if self._server:
+            raise RuntimeError("The server is already running")
+
+        import uvicorn
+
+        if configure_logger:
+            configure_logger_func()
+        if configure_telemetry:
+            configure_telemetry_func()
+
+        config = uvicorn.Config(
+            create_app(*self._agents),
+            host,
+            port,
+            uds,
+            fd,
+            loop,
+            http,
+            ws,
+            ws_max_size,
+            ws_max_queue,
+            ws_ping_interval,
+            ws_ping_timeout,
+            ws_per_message_deflate,
+            lifespan,
+            env_file,
+            log_config,
+            log_level,
+            access_log,
+            use_colors,
+            interface,
+            reload,
+            reload_dirs,
+            reload_delay,
+            reload_includes,
+            reload_excludes,
+            workers,
+            proxy_headers,
+            server_header,
+            date_header,
+            forwarded_allow_ips,
+            root_path,
+            limit_concurrency,
+            limit_max_requests,
+            backlog,
+            timeout_keep_alive,
+            timeout_notify,
+            timeout_graceful_shutdown,
+            callback_notify,
+            ssl_keyfile,
+            ssl_certfile,
+            ssl_keyfile_password,
+            ssl_version,
+            ssl_cert_reqs,
+            ssl_ca_certs,
+            ssl_ciphers,
+            headers,
+            factory,
+            h11_max_incomplete_event_size,
+        )
+        self._server = uvicorn.Server(config)
+        self._server.run()
+
+    @property
+    def should_exit(self) -> bool:
+        return self._server.should_exit if self._server else False
+
+    @should_exit.setter
+    def should_exit(self, value: bool) -> None:
+        self._server.should_exit = value

acp_sdk/server/session.py

@@ -0,0 +1,21 @@
+import uuid
+from collections.abc import Iterator
+
+from acp_sdk.models import Message, SessionId
+from acp_sdk.models.models import RunStatus
+from acp_sdk.server.bundle import RunBundle
+
+
+class Session:
+    def __init__(self) -> None:
+        self.id: SessionId = uuid.uuid4()
+        self.bundles: list[RunBundle] = []
+
+    def append(self, bundle: RunBundle) -> None:
+        self.bundles.append(bundle)
+
+    def history(self) -> Iterator[Message]:
+        for bundle in self.bundles:
+            if bundle.run.status == RunStatus.COMPLETED:
+                yield from bundle.inputs
+                yield from bundle.run.outputs

acp_sdk/server/telemetry.py

@@ -0,0 +1,57 @@
+import logging
+
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import (
+    SERVICE_NAME,
+    SERVICE_NAMESPACE,
+    SERVICE_VERSION,
+    Resource,
+)
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from acp_sdk.version import __version__
+
+root_logger = logging.getLogger()
+
+
+def configure_telemetry() -> None:
+    """Utility that configures opentelemetry with OTLP exporter"""
+
+    resource = Resource(
+        attributes={
+            SERVICE_NAME: "acp-server",
+            SERVICE_NAMESPACE: "acp",
+            SERVICE_VERSION: __version__,
+        }
+    )
+
+    # Traces
+    provider = TracerProvider(resource=resource)
+    processor = BatchSpanProcessor(OTLPSpanExporter())
+    provider.add_span_processor(processor)
+    trace.set_tracer_provider(provider)
+
+    # Metrics
+    meter_provider = MeterProvider(
+        resource=resource,
+        metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())],
+    )
+    metrics.set_meter_provider(meter_provider)
+
+    # Logs
+    logger_provider = LoggerProvider(resource=resource)
+    processor = BatchLogRecordProcessor(OTLPLogExporter())
+    logger_provider.add_log_record_processor(processor)
+    root_logger.addHandler(LoggingHandler(logger_provider=logger_provider))
+
+
+def get_tracer() -> trace.Tracer:
+    return trace.get_tracer("acp-sdk", __version__)

acp_sdk/server/types.py

@@ -0,0 +1,6 @@
+from typing import Any
+
+from acp_sdk.models import Await, AwaitResume, Message
+
+RunYield = Message | Await | dict[str | Any]
+RunYieldResume = AwaitResume | None

acp_sdk/server/utils.py

@@ -0,0 +1,14 @@
+from collections.abc import AsyncGenerator
+
+from pydantic import BaseModel
+
+from acp_sdk.server.bundle import RunBundle
+
+
+def encode_sse(model: BaseModel) -> str:
+    return f"data: {model.model_dump_json()}\n\n"
+
+
+async def stream_sse(bundle: RunBundle) -> AsyncGenerator[str]:
+    async for event in bundle.stream():
+        yield encode_sse(event)