pyagentic-core 2.9.1.dev1__tar.gz → 2.10.1.dev2__tar.gz

{pyagentic_core-2.9.1.dev1/pyagentic_core.egg-info → pyagentic_core-2.10.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.9.1.dev1
+Version: 2.10.1.dev2
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2}/pyagentic/api/__init__.py

@@ -21,6 +21,17 @@ from pyagentic.api._config import (
 )
 from pyagentic.api._docker import generate_dockerfile, write_dockerfile
 from pyagentic.api._mcp_server import mount_mcp
+from pyagentic.api._models import (
+    AgentInfo,
+    AppAgentEntry,
+    AppIndex,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    DeleteSessionResponse,
+    HealthResponse,
+    ListSessionsResponse,
+    SchemaResponse,
+)
 from pyagentic.api._sessions import SessionManager
 
 __all__ = [
@@ -35,4 +46,14 @@ __all__ = [
     "JobsConfig",
     "load_config",
     "SessionManager",
+    # HTTP request/response models
+    "AgentInfo",
+    "AppAgentEntry",
+    "AppIndex",
+    "CreateSessionRequest",
+    "CreateSessionResponse",
+    "DeleteSessionResponse",
+    "HealthResponse",
+    "ListSessionsResponse",
+    "SchemaResponse",
 ]

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2}/pyagentic/api/_app.py

@@ -24,12 +24,22 @@ from typing import Optional, Union
 from dotenv import load_dotenv
 from fastapi import APIRouter, FastAPI, HTTPException
 from fastapi.responses import StreamingResponse
-from pydantic import BaseModel
 
 from pyagentic._base._agent._agent import BaseAgent
 from pyagentic.models.llm import LLMResponse
 from pyagentic.models.response import AgentResponse, ToolResponse
 from pyagentic.api._config import AgentsConfig, JobsConfig, load_config
+from pyagentic.api._models import (
+    AgentInfo,
+    AppAgentEntry,
+    AppIndex,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    DeleteSessionResponse,
+    HealthResponse,
+    ListSessionsResponse,
+    SchemaResponse,
+)
 from pyagentic.api._sessions import SessionManager
 
 # Agents may be passed as a single class, a list of classes, or a
@@ -37,19 +47,6 @@ from pyagentic.api._sessions import SessionManager
 AgentsArg = Union[type[BaseAgent], list[type[BaseAgent]], dict[str, type[BaseAgent]]]
 
 
-class CreateSessionRequest(BaseModel):
-    """Request body for creating a new agent session.
-
-    Attributes:
-        model (Optional[str]): LLM model string override
-            (e.g. ``'openai::gpt-4o'``).
-        api_key (Optional[str]): API key for the model provider.
-    """
-
-    model: Optional[str] = None
-    api_key: Optional[str] = None
-
-
 _REQUIRED_AGENT_ATTRS = (
     "__request_model__",
     "__response_model__",
@@ -105,14 +102,23 @@ def _store_path_for(base: str, prefix: str, multi: bool) -> str:
     return str(p.with_name(f"{p.stem}-{slug}{p.suffix}"))
 
 
+def _normalize_prefix(prefix: str) -> str:
+    """Normalize a mount prefix: '' stays root, others get a single leading slash."""
+    prefix = prefix.strip()
+    if not prefix or prefix == "/":
+        return ""
+    return "/" + prefix.strip("/")
+
+
 def _normalize_agents(agents: AgentsArg) -> dict[str, type[BaseAgent]]:
     """Normalize the ``agents`` argument into a {prefix: class} mapping.
 
     A single class is mounted at the root (""); a list derives a prefix from
-    each class name; a dict is used as-is.
+    each class name; a dict's keys are used as prefixes (a leading slash is
+    added if missing, so ``{"duck": Duck}`` and ``{"/duck": Duck}`` are equivalent).
     """
     if isinstance(agents, dict):
-        mapping = dict(agents)
+        mapping = {_normalize_prefix(k): v for k, v in agents.items()}
     elif isinstance(agents, (list, tuple)):
         if len(agents) == 1:
             mapping = {"": agents[0]}
@@ -212,32 +218,32 @@ def create_router(
 
     # ---- info routes ----
 
-    @router.get("/", name=f"{slug}_info")
-    async def agent_info() -> dict:
+    @router.get("/", response_model=AgentInfo, name=f"{slug}_info")
+    async def agent_info() -> AgentInfo:
         """Return basic agent metadata."""
-        return {
-            "name": name,
-            "version": version,
-            "agent_class": agent_class.__name__,
-            "tools": list(agent_class.__tool_defs__.keys()),
-            "state_fields": list(agent_class.__state_defs__.keys()),
-            "linked_agents": list(agent_class.__linked_agents__.keys()),
-        }
-
-    @router.get("/health", name=f"{slug}_health")
-    async def health() -> dict:
+        return AgentInfo(
+            name=name,
+            version=version,
+            agent_class=agent_class.__name__,
+            tools=list(agent_class.__tool_defs__.keys()),
+            state_fields=list(agent_class.__state_defs__.keys()),
+            linked_agents=list(agent_class.__linked_agents__.keys()),
+        )
+
+    @router.get("/health", response_model=HealthResponse, name=f"{slug}_health")
+    async def health() -> HealthResponse:
         """Liveness probe endpoint."""
-        return {"status": "ok"}
+        return HealthResponse()
 
-    @router.get("/schema", name=f"{slug}_schema")
-    async def schema() -> dict:
+    @router.get("/schema", response_model=SchemaResponse, name=f"{slug}_schema")
+    async def schema() -> SchemaResponse:
         """Return JSON schemas for request, response, stream event, and state models."""
-        return {
-            "request": RequestModel.model_json_schema(),
-            "response": ResponseModel.model_json_schema(),
-            "stream_event": StreamEventModel.model_json_schema(),
-            "state": StateModel.model_json_schema(),
-        }
+        return SchemaResponse(
+            request=RequestModel.model_json_schema(),
+            response=ResponseModel.model_json_schema(),
+            stream_event=StreamEventModel.model_json_schema(),
+            state=StateModel.model_json_schema(),
+        )
 
     if sessions:
         _register_session_routes(
@@ -307,27 +313,42 @@ def _register_session_routes(
 
     # ---- session routes ----
 
-    @router.post("/sessions", status_code=201, name=f"{slug}_create_session")
-    async def create_session(req: Optional[CreateSessionRequest] = None) -> dict:
+    @router.post(
+        "/sessions",
+        status_code=201,
+        response_model=CreateSessionResponse,
+        name=f"{slug}_create_session",
+    )
+    async def create_session(
+        req: Optional[CreateSessionRequest] = None,
+    ) -> CreateSessionResponse:
         """Create a new agent session."""
         model = req.model if req else None
         api_key = req.api_key if req else None
         session_id = sessions.create(model=model, api_key=api_key)
-        return {"session_id": session_id}
+        return CreateSessionResponse(session_id=session_id)
 
-    @router.get("/sessions", name=f"{slug}_list_sessions")
-    async def list_sessions() -> dict:
+    @router.get(
+        "/sessions",
+        response_model=ListSessionsResponse,
+        name=f"{slug}_list_sessions",
+    )
+    async def list_sessions() -> ListSessionsResponse:
         """List all active session IDs."""
-        return {"sessions": sessions.list_sessions()}
+        return ListSessionsResponse(sessions=sessions.list_sessions())
 
-    @router.delete("/sessions/{session_id}", name=f"{slug}_delete_session")
-    async def delete_session(session_id: str) -> dict:
+    @router.delete(
+        "/sessions/{session_id}",
+        response_model=DeleteSessionResponse,
+        name=f"{slug}_delete_session",
+    )
+    async def delete_session(session_id: str) -> DeleteSessionResponse:
         """Delete an existing session."""
         try:
             sessions.delete(session_id)
         except KeyError:
             raise HTTPException(status_code=404, detail="Session not found")
-        return {"deleted": session_id}
+        return DeleteSessionResponse(deleted=session_id)
 
     # ---- chat routes ----
 
@@ -547,7 +568,9 @@ def create_app(
             jobs_config=jobs_cfg,
         )
         app.include_router(router, prefix=prefix)
-        index.append({"agent_class": agent_class.__name__, "prefix": prefix or "/"})
+        index.append(
+            AppAgentEntry(agent_class=agent_class.__name__, prefix=prefix or "/")
+        )
         if mcp:
             mount_mcp(
                 app,
@@ -566,14 +589,14 @@ def create_app(
     # When no agent occupies the root, add a top-level index + health probe.
     if not mounted_at_root:
 
-        @app.get("/")
-        async def app_index() -> dict:
+        @app.get("/", response_model=AppIndex)
+        async def app_index() -> AppIndex:
             """List the agents mounted on this app."""
-            return {"name": name, "version": version, "agents": index}
+            return AppIndex(name=name, version=version, agents=index)
 
-        @app.get("/health")
-        async def app_health() -> dict:
+        @app.get("/health", response_model=HealthResponse)
+        async def app_health() -> HealthResponse:
             """Liveness probe endpoint."""
-            return {"status": "ok"}
+            return HealthResponse()
 
     return app

pyagentic_core-2.10.1.dev2/pyagentic/api/_models.py

@@ -0,0 +1,128 @@
+"""
+Request and response models for the HTTP API surface.
+
+These cover the static (agent-independent) endpoints — info, health, schema,
+sessions CRUD, and the multi-agent app index. The chat, stream, and state
+endpoints are typed directly from each agent's metaclass-generated models
+(``__request_model__`` / ``__response_model__`` / ``__stream_event_model__`` /
+``__state_class__``), so they are not duplicated here.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CreateSessionRequest(BaseModel):
+    """Request body for creating a new agent session.
+
+    Attributes:
+        model (Optional[str]): LLM model string override
+            (e.g. ``'openai::gpt-4o'``).
+        api_key (Optional[str]): API key for the model provider.
+    """
+
+    model: Optional[str] = None
+    api_key: Optional[str] = None
+
+
+class CreateSessionResponse(BaseModel):
+    """Response returned after creating a session.
+
+    Attributes:
+        session_id (str): Identifier of the newly created session.
+    """
+
+    session_id: str
+
+
+class ListSessionsResponse(BaseModel):
+    """Response listing the active session IDs.
+
+    Attributes:
+        sessions (list[str]): Active session identifiers.
+    """
+
+    sessions: list[str] = Field(default_factory=list)
+
+
+class DeleteSessionResponse(BaseModel):
+    """Response returned after deleting a session.
+
+    Attributes:
+        deleted (str): Identifier of the deleted session.
+    """
+
+    deleted: str
+
+
+class HealthResponse(BaseModel):
+    """Liveness probe response.
+
+    Attributes:
+        status (str): Always ``"ok"`` when the service is up.
+    """
+
+    status: str = "ok"
+
+
+class AgentInfo(BaseModel):
+    """Metadata describing a single mounted agent.
+
+    Attributes:
+        name (str): Display name for the agent.
+        version (str): Version string for the deployment.
+        agent_class (str): The agent class name.
+        tools (list[str]): Names of the tools the agent exposes.
+        state_fields (list[str]): Names of the agent's state fields.
+        linked_agents (list[str]): Names of agents linked to this one.
+    """
+
+    name: str
+    version: str
+    agent_class: str
+    tools: list[str] = Field(default_factory=list)
+    state_fields: list[str] = Field(default_factory=list)
+    linked_agents: list[str] = Field(default_factory=list)
+
+
+class SchemaResponse(BaseModel):
+    """JSON schemas for an agent's request/response/stream/state models.
+
+    Attributes:
+        request (dict): JSON schema of the agent's request model.
+        response (dict): JSON schema of the agent's response model.
+        stream_event (dict): JSON schema of the agent's stream event model.
+        state (dict): JSON schema of the agent's state model.
+    """
+
+    request: dict
+    response: dict
+    stream_event: dict
+    state: dict
+
+
+class AppAgentEntry(BaseModel):
+    """One agent entry in the multi-agent app index.
+
+    Attributes:
+        agent_class (str): The agent class name.
+        prefix (str): URL prefix the agent is mounted under.
+    """
+
+    agent_class: str
+    prefix: str
+
+
+class AppIndex(BaseModel):
+    """Top-level index of agents mounted on a multi-agent app.
+
+    Attributes:
+        name (str): App name.
+        version (str): App version.
+        agents (list[AppAgentEntry]): The mounted agents.
+    """
+
+    name: str
+    version: str
+    agents: list[AppAgentEntry] = Field(default_factory=list)

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2}/pyagentic/api/jobs/_models.py

@@ -124,6 +124,97 @@ class BackendHealth(BaseModel):
     detail: dict = Field(default_factory=dict)
 
 
+# --- HTTP request/response models for the /jobs routes ---------------------
+#
+# These are the wire models for the job endpoints. ``JobSnapshot`` carries a
+# loosely-typed ``result`` (Optional[Any]); ``build_jobs_router`` subclasses it
+# per-agent so ``result`` is typed as the agent's ``__response_model__``.
+
+
+class JobSummary(BaseModel):
+    """A job's status without its result payload (used in list responses).
+
+    Attributes:
+        job_id (str): Unique job identifier.
+        session_id (Optional[str]): Session the job belongs to, if any.
+        status (JobStatus): Current lifecycle state.
+        created_at (float): Unix timestamp of submission.
+        started_at (Optional[float]): Unix timestamp when execution began.
+        finished_at (Optional[float]): Unix timestamp of terminal transition.
+        error (Optional[str]): Failure description, set when the job fails.
+    """
+
+    job_id: str
+    session_id: Optional[str] = None
+    status: JobStatus
+    created_at: float
+    started_at: Optional[float] = None
+    finished_at: Optional[float] = None
+    error: Optional[str] = None
+
+
+class JobSnapshot(JobSummary):
+    """A job's status plus its result when terminal.
+
+    Attributes:
+        result (Optional[Any]): The final agent response, present once the job
+            has succeeded. ``build_jobs_router`` narrows this to the agent's
+            ``__response_model__`` per deployment.
+    """
+
+    result: Optional[Any] = None
+
+
+class JobSubmitResponse(BaseModel):
+    """Response returned after submitting a job (HTTP 202).
+
+    Attributes:
+        job_id (str): Identifier of the newly queued job.
+        status (JobStatus): Lifecycle state at submission time (``queued``).
+    """
+
+    job_id: str
+    status: JobStatus
+
+
+class JobListResponse(BaseModel):
+    """Response listing jobs newest-first.
+
+    Attributes:
+        jobs (list[JobSummary]): The matching job summaries.
+    """
+
+    jobs: list[JobSummary] = Field(default_factory=list)
+
+
+class JobUpdateEntry(BaseModel):
+    """One parsed entry of a job's update log.
+
+    Attributes:
+        seq (int): Monotonic per-job sequence number.
+        event (str): SSE event name.
+        data (Any): The parsed update payload.
+    """
+
+    seq: int
+    event: str
+    data: Any = None
+
+
+class JobUpdatesResponse(BaseModel):
+    """Response returning a job's update log past a cursor.
+
+    Attributes:
+        job_id (str): The job identifier.
+        status (JobStatus): Current lifecycle state of the job.
+        updates (list[JobUpdateEntry]): Updates past the requested cursor.
+    """
+
+    job_id: str
+    status: JobStatus
+    updates: list[JobUpdateEntry] = Field(default_factory=list)
+
+
 def _build_prompt(request: dict) -> str:
     """Collapse agent request kwargs into the single prompt string step() accepts.
 

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2}/pyagentic/api/jobs/_routes.py

@@ -15,8 +15,12 @@ from pydantic import create_model
 from pyagentic._base._agent._agent import BaseAgent
 from pyagentic.api._sessions import SessionManager
 from pyagentic.api.jobs._models import (
+    JobListResponse,
     JobRecord,
+    JobSnapshot,
     JobStatus,
+    JobSubmitResponse,
+    JobUpdatesResponse,
     TERMINAL_EVENTS,
 )
 from pyagentic.api.jobs._orchestrator import JobOrchestrator
@@ -134,6 +138,7 @@ def build_jobs_router(
     """
     router = APIRouter()
     RequestModel = agent_class.__request_model__
+    ResponseModel = agent_class.__response_model__
 
     SubmitModel = create_model(
         f"{agent_class.__name__}JobSubmitRequest",
@@ -141,7 +146,15 @@ def build_jobs_router(
         session_id=(Optional[str], None),
     )
 
-    @router.post("/jobs", status_code=202)
+    # Narrow the loosely-typed JobSnapshot.result to this agent's response model
+    # so the get/cancel endpoints document the exact result shape.
+    SnapshotModel = create_model(
+        f"{agent_class.__name__}JobSnapshot",
+        __base__=JobSnapshot,
+        result=(Optional[ResponseModel], None),
+    )
+
+    @router.post("/jobs", status_code=202, response_model=JobSubmitResponse)
     async def submit_job(req: SubmitModel) -> dict:  # type: ignore[valid-type]
         """Submit an agent run as an async job."""
         await orchestrator.ensure_started()
@@ -153,7 +166,7 @@ def build_jobs_router(
         job = await orchestrator.submit(request, session_id=req.session_id)
         return {"job_id": job.job_id, "status": job.status.value}
 
-    @router.get("/jobs")
+    @router.get("/jobs", response_model=JobListResponse)
     async def list_jobs(
         status: Optional[JobStatus] = None,
         session_id: Optional[str] = None,
@@ -167,7 +180,7 @@ def build_jobs_router(
         )
         return {"jobs": [_snapshot(r, include_result=False) for r in records]}
 
-    @router.get("/jobs/{job_id}")
+    @router.get("/jobs/{job_id}", response_model=SnapshotModel)
     async def get_job(job_id: str) -> dict:
         """Return a job's status and, when terminal, its result."""
         await orchestrator.ensure_started()
@@ -176,7 +189,7 @@ def build_jobs_router(
             raise HTTPException(status_code=404, detail="Job not found")
         return _snapshot(record)
 
-    @router.get("/jobs/{job_id}/updates")
+    @router.get("/jobs/{job_id}/updates", response_model=JobUpdatesResponse)
     async def get_updates(job_id: str, since: int = -1) -> dict:
         """Return a job's update log past the given seq cursor.
 
@@ -225,7 +238,7 @@ def build_jobs_router(
             headers=_SSE_HEADERS,
         )
 
-    @router.post("/jobs/{job_id}/cancel")
+    @router.post("/jobs/{job_id}/cancel", response_model=SnapshotModel)
     async def cancel_job(job_id: str) -> dict:
         """Cancel a queued or running job."""
         await orchestrator.ensure_started()

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2/pyagentic_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.9.1.dev1
+Version: 2.10.1.dev2
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

{pyagentic_core-2.9.1.dev1 → pyagentic_core-2.10.1.dev2}/pyagentic_core.egg-info/SOURCES.txt

@@ -63,6 +63,7 @@ pyagentic/api/_app.py
 pyagentic/api/_config.py
 pyagentic/api/_docker.py
 pyagentic/api/_mcp_server.py
+pyagentic/api/_models.py
 pyagentic/api/_sessions.py
 pyagentic/api/jobs/__init__.py
 pyagentic/api/jobs/_models.py