pyagentic-core 2.8.1.dev1__tar.gz → 2.9.0a1__tar.gz

{pyagentic_core-2.8.1.dev1/pyagentic_core.egg-info → pyagentic_core-2.9.0a1}/PKG-INFO

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

{pyagentic_core-2.8.1.dev1 → pyagentic_core-2.9.0a1}/pyagentic/api/_app.py

@@ -29,7 +29,7 @@ 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, load_config
+from pyagentic.api._config import AgentsConfig, JobsConfig, load_config
 from pyagentic.api._sessions import SessionManager
 
 # Agents may be passed as a single class, a list of classes, or a
@@ -79,16 +79,21 @@ def _validate_agent_class(cls: type) -> None:
         )
 
 
+def _slugify(value: str) -> str:
+    """Convert a CamelCase or arbitrary name into a kebab-case URL/route slug."""
+    # Insert a hyphen at lower/digit -> upper boundaries (CamelCase -> kebab).
+    slug = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "-", value).lower()
+    # Collapse any remaining non-alphanumeric runs into single hyphens.
+    slug = re.sub(r"[^a-z0-9]+", "-", slug).strip("-")
+    return slug or "agent"
+
+
 def _default_prefix(agent_class: type[BaseAgent]) -> str:
     """Derive a URL prefix from an agent class name (e.g. ResearchAgent -> /research)."""
     name = agent_class.__name__
     if name.endswith("Agent") and len(name) > len("Agent"):
         name = name[: -len("Agent")]
-    # Insert a hyphen at lower/digit -> upper boundaries (CamelCase -> kebab).
-    name = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "-", name).lower()
-    # Collapse any remaining non-alphanumeric runs into single hyphens.
-    name = re.sub(r"[^a-z0-9]+", "-", name).strip("-")
-    return "/" + name
+    return "/" + _slugify(name)
 
 
 def _store_path_for(base: str, prefix: str, multi: bool) -> str:
@@ -135,33 +140,60 @@ def create_router(
     model: Optional[str] = None,
     name: Optional[str] = None,
     version: str = "0.1.0",
+    tags: Optional[list[str]] = None,
+    sessions: bool = True,
+    jobs: bool = False,
+    jobs_config: Optional["JobsConfig"] = None,
 ) -> APIRouter:
     """Build a FastAPI ``APIRouter`` exposing a single agent's endpoints.
 
-    Mount it onto an existing FastAPI app::
+    Mount it onto an existing FastAPI app under whatever prefix you like::
 
-        app.include_router(create_router(MyAgent), prefix="/agent")
+        app.include_router(create_router(MyAgent, name="my-agent"), prefix="/agents/my-agent")
 
     The router owns its own :class:`SessionManager`, exposed as
     ``router.sessions`` so callers can share it (e.g. with :func:`mount_mcp`).
+    When ``jobs`` is enabled, the job orchestrator is exposed as
+    ``router.orchestrator`` (otherwise ``None``) so callers can wire its
+    lifecycle into their app's lifespan.
+
+    Every route is given a unique ``name`` derived from ``name`` (e.g.
+    ``my-agent_chat``), so multiple agents can be mounted on one app without
+    colliding and individual routes remain addressable via ``url_path_for``.
 
     Routes registered (relative to the mount point):
       - ``GET /`` agent info, ``GET /health``, ``GET /schema``
-      - ``POST/GET /sessions``, ``DELETE /sessions/{id}``
-      - ``POST /sessions/{id}/chat``, ``POST /sessions/{id}/chat/stream``
-      - ``GET /sessions/{id}/state``
+      - when ``sessions``: ``POST/GET /sessions``, ``DELETE /sessions/{id}``,
+        ``POST /sessions/{id}/chat``, ``POST /sessions/{id}/chat/stream``,
+        ``GET /sessions/{id}/state``
+      - when ``jobs``: ``POST/GET /jobs``, ``GET /jobs/{id}``,
+        ``GET /jobs/{id}/updates``, ``GET /jobs/{id}/stream``,
+        ``POST /jobs/{id}/cancel``
 
     Args:
         agent_class (type[BaseAgent]): The agent class to serve.
         model (Optional[str]): Default model for sessions. ``None`` falls back to
             the agent's own default.
-        name (Optional[str]): Display name for the info route. Defaults to the
-            class name.
+        name (Optional[str]): Display name for the info route and basis for
+            route names/tags. Defaults to the class name.
         version (str): Version string for the info route.
+        tags (Optional[list[str]]): OpenAPI tags applied to every route on the
+            router (groups them in the docs). ``None`` leaves routes untagged.
+        sessions (bool): If True, mount the session-based routes (create/list/
+            delete sessions plus synchronous chat, streaming chat, and state).
+            If False, those routes are omitted — interaction happens only via
+            ``jobs``.
+        jobs (bool): If True, mount a durable async job system at ``/jobs`` whose
+            orchestrator is exposed as ``router.orchestrator``. The caller is
+            responsible for starting/stopping that orchestrator (see
+            :func:`create_app`, which does this automatically).
+        jobs_config (Optional[JobsConfig]): Configuration for the job system when
+            ``jobs`` is True. Defaults to :class:`JobsConfig` defaults.
 
     Returns:
-        APIRouter: A router with all agent routes registered, with its
-            ``SessionManager`` attached as ``router.sessions``.
+        APIRouter: A router with the selected agent routes registered, with its
+            ``SessionManager`` attached as ``router.sessions`` and its job
+            orchestrator (or ``None``) as ``router.orchestrator``.
 
     Raises:
         TypeError: If agent_class is missing required metaclass attributes.
@@ -169,17 +201,18 @@ def create_router(
     _validate_agent_class(agent_class)
 
     name = name or agent_class.__name__
+    slug = _slugify(name)
     RequestModel = agent_class.__request_model__
     ResponseModel = agent_class.__response_model__
     StreamEventModel = agent_class.__stream_event_model__
     StateModel = agent_class.__state_class__
 
-    router = APIRouter()
-    sessions = SessionManager(agent_class, default_model=model)
+    router = APIRouter(tags=tags)
+    session_manager = SessionManager(agent_class, default_model=model)
 
     # ---- info routes ----
 
-    @router.get("/")
+    @router.get("/", name=f"{slug}_info")
     async def agent_info() -> dict:
         """Return basic agent metadata."""
         return {
@@ -191,12 +224,12 @@ def create_router(
             "linked_agents": list(agent_class.__linked_agents__.keys()),
         }
 
-    @router.get("/health")
+    @router.get("/health", name=f"{slug}_health")
     async def health() -> dict:
         """Liveness probe endpoint."""
         return {"status": "ok"}
 
-    @router.get("/schema")
+    @router.get("/schema", name=f"{slug}_schema")
     async def schema() -> dict:
         """Return JSON schemas for request, response, stream event, and state models."""
         return {
@@ -206,9 +239,75 @@ def create_router(
             "state": StateModel.model_json_schema(),
         }
 
+    if sessions:
+        _register_session_routes(
+            router,
+            slug,
+            session_manager,
+            RequestModel,
+            ResponseModel,
+            StreamEventModel,
+            StateModel,
+        )
+
+    # Expose the session manager so callers can share it (e.g. with mount_mcp).
+    router.sessions = session_manager
+
+    orchestrator = None
+    if jobs:
+        orchestrator = _mount_jobs_router(
+            router,
+            agent_class,
+            session_manager,
+            jobs_config or JobsConfig(),
+            model,
+            tags,
+        )
+    router.orchestrator = orchestrator
+
+    return router
+
+
+def _mount_jobs_router(
+    router: APIRouter,
+    agent_class: type[BaseAgent],
+    sessions: SessionManager,
+    jobs_config: "JobsConfig",
+    default_model: Optional[str],
+    tags: Optional[list[str]],
+) -> "JobOrchestrator":
+    """Build a job orchestrator and include its /jobs router; return the orchestrator."""
+    from pyagentic.api.jobs import JobOrchestrator, build_backend, build_store
+    from pyagentic.api.jobs._routes import build_jobs_router
+
+    store = build_store(jobs_config.store)
+    backend = build_backend(
+        agent_class,
+        sessions,
+        max_concurrency=jobs_config.max_concurrency,
+        default_model=default_model,
+    )
+    orchestrator = JobOrchestrator(store, backend, jobs_config, sessions)
+    router.include_router(
+        build_jobs_router(orchestrator, agent_class, sessions), tags=tags
+    )
+    return orchestrator
+
+
+def _register_session_routes(
+    router: APIRouter,
+    slug: str,
+    sessions: SessionManager,
+    RequestModel: type,
+    ResponseModel: type,
+    StreamEventModel: type,
+    StateModel: type,
+) -> None:
+    """Register the session-based routes (sessions CRUD, chat, stream, state)."""
+
     # ---- session routes ----
 
-    @router.post("/sessions", status_code=201)
+    @router.post("/sessions", status_code=201, name=f"{slug}_create_session")
     async def create_session(req: Optional[CreateSessionRequest] = None) -> dict:
         """Create a new agent session."""
         model = req.model if req else None
@@ -216,12 +315,12 @@ def create_router(
         session_id = sessions.create(model=model, api_key=api_key)
         return {"session_id": session_id}
 
-    @router.get("/sessions")
+    @router.get("/sessions", name=f"{slug}_list_sessions")
     async def list_sessions() -> dict:
         """List all active session IDs."""
         return {"sessions": sessions.list_sessions()}
 
-    @router.delete("/sessions/{session_id}")
+    @router.delete("/sessions/{session_id}", name=f"{slug}_delete_session")
     async def delete_session(session_id: str) -> dict:
         """Delete an existing session."""
         try:
@@ -232,7 +331,11 @@ def create_router(
 
     # ---- chat routes ----
 
-    @router.post("/sessions/{session_id}/chat", response_model=ResponseModel)
+    @router.post(
+        "/sessions/{session_id}/chat",
+        response_model=ResponseModel,
+        name=f"{slug}_chat",
+    )
     async def chat(session_id: str, req: RequestModel):  # type: ignore[valid-type]
         """Send a message and receive a complete agent response."""
         try:
@@ -247,6 +350,7 @@ def create_router(
     @router.post(
         "/sessions/{session_id}/chat/stream",
         response_model=StreamEventModel,
+        name=f"{slug}_chat_stream",
         responses={
             200: {
                 "description": (
@@ -307,7 +411,11 @@ def create_router(
 
     # ---- state route ----
 
-    @router.get("/sessions/{session_id}/state", response_model=StateModel)
+    @router.get(
+        "/sessions/{session_id}/state",
+        response_model=StateModel,
+        name=f"{slug}_get_state",
+    )
     async def get_state(session_id: str):
         """Return the current state of the agent for a session."""
         try:
@@ -316,11 +424,6 @@ def create_router(
             raise HTTPException(status_code=404, detail="Session not found")
         return agent.state
 
-    # Expose the session manager so callers can share it (e.g. with mount_mcp).
-    router.sessions = sessions
-
-    return router
-
 
 def _wire_jobs_lifespan(app: FastAPI, orchestrators: list) -> None:
     """Start/stop the per-agent job orchestrators inside the app's lifespan.
@@ -360,6 +463,7 @@ def create_app(
     description: Optional[str] = None,
     model: Optional[str] = None,
     mcp: bool = False,
+    sessions: bool = True,
     jobs: bool = False,
 ) -> FastAPI:
     """Build a standalone FastAPI app serving one or several agents.
@@ -388,6 +492,10 @@ def create_app(
         model (Optional[str]): Default model for all agents' sessions. Overrides
             config.
         mcp (bool): If True, mount an MCP endpoint per agent at ``<prefix>/mcp``.
+        sessions (bool): If True (default), mount the session-based routes
+            (sessions CRUD plus synchronous/streaming chat and state) for each
+            agent. If False, those routes are omitted — pair with ``jobs`` to
+            serve agents purely through the async job API.
         jobs (bool): If True (or ``[jobs].enabled`` in config), mount a durable
             async job system per agent at ``<prefix>/jobs`` — runs submitted there
             execute in the background and survive client timeouts/reconnects.
@@ -420,7 +528,24 @@ def create_app(
     index = []
     orchestrators = []
     for prefix, agent_class in mapping.items():
-        router = create_router(agent_class, model=model, name=name, version=version)
+        # The root agent inherits the app's display name; agents under a prefix
+        # take a name derived from that prefix, so each router's route names stay
+        # unique across the app.
+        agent_name = name if prefix == "" else prefix.strip("/").replace("/", "-")
+        jobs_cfg = None
+        if jobs_enabled:
+            jobs_cfg = config.jobs.model_copy(
+                update={"store": _store_path_for(config.jobs.store, prefix, multi)}
+            )
+        router = create_router(
+            agent_class,
+            model=model,
+            name=agent_name,
+            version=version,
+            sessions=sessions,
+            jobs=jobs_enabled,
+            jobs_config=jobs_cfg,
+        )
         app.include_router(router, prefix=prefix)
         index.append({"agent_class": agent_class.__name__, "prefix": prefix or "/"})
         if mcp:
@@ -432,23 +557,8 @@ def create_app(
                 sessions=router.sessions,
                 path=(prefix + "/mcp"),
             )
-        if jobs_enabled:
-            from pyagentic.api.jobs import JobOrchestrator, build_backend, build_store
-            from pyagentic.api.jobs._routes import build_jobs_router
-
-            store = build_store(_store_path_for(config.jobs.store, prefix, multi))
-            backend = build_backend(
-                agent_class,
-                router.sessions,
-                max_concurrency=config.jobs.max_concurrency,
-                default_model=model,
-            )
-            orchestrator = JobOrchestrator(store, backend, config.jobs, router.sessions)
-            app.include_router(
-                build_jobs_router(orchestrator, agent_class, router.sessions),
-                prefix=prefix,
-            )
-            orchestrators.append(orchestrator)
+        if router.orchestrator is not None:
+            orchestrators.append(router.orchestrator)
 
     if orchestrators:
         _wire_jobs_lifespan(app, orchestrators)

{pyagentic_core-2.8.1.dev1 → pyagentic_core-2.9.0a1/pyagentic_core.egg-info}/PKG-INFO

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

{pyagentic_core-2.8.1.dev1 → pyagentic_core-2.9.0a1}/tests/api/test_app.py

@@ -150,3 +150,24 @@ def test_jobs_enabled_multi_agent_prefixed():
     paths = {getattr(r, "path", None) for r in app.routes}
     assert "/app-test/jobs" in paths
     assert "/writer/jobs" in paths
+
+
+# ---- sessions opt-out ----
+
+
+def test_sessions_disabled():
+    """sessions=False omits the session routes from the app."""
+    app = create_app(_AppTestAgent, model="_mock::test-model", sessions=False)
+    paths = {getattr(r, "path", None) for r in app.routes}
+    assert "/sessions" not in paths
+    assert "/schema" in paths  # info routes remain
+
+
+def test_sessions_off_jobs_on():
+    """An async-only app: no /sessions, but /jobs is served."""
+    app = create_app(
+        _AppTestAgent, model="_mock::test-model", sessions=False, jobs=True
+    )
+    paths = {getattr(r, "path", None) for r in app.routes}
+    assert "/sessions" not in paths
+    assert "/jobs" in paths

{pyagentic_core-2.8.1.dev1 → pyagentic_core-2.9.0a1}/tests/api/test_router.py

@@ -79,3 +79,66 @@ def test_two_routers_isolated_sessions():
     sid = client.post("/a/sessions").json()["session_id"]
     assert sid in client.get("/a/sessions").json()["sessions"]
     assert sid not in client.get("/b/sessions").json()["sessions"]
+
+
+def test_routes_are_named():
+    """Each route gets a name derived from the agent name, for url reversal."""
+    router = create_router(_RouterTestAgent, name="my-agent", model="_mock::test-model")
+    names = {route.name for route in router.routes}
+    assert {"my-agent_info", "my-agent_chat", "my-agent_get_state"} <= names
+
+
+def test_tags_applied():
+    """The tags arg is attached to every route on the router."""
+    router = create_router(
+        _RouterTestAgent, model="_mock::test-model", tags=["bots"]
+    )
+    assert all("bots" in route.tags for route in router.routes)
+
+
+def test_named_routes_unique_across_mounts():
+    """Distinct names keep route names unique when mounted on one app."""
+    app = FastAPI()
+    app.include_router(
+        create_router(_RouterTestAgent, name="a", model="_mock::test-model"), prefix="/a"
+    )
+    app.include_router(
+        create_router(_RouterTestAgent, name="b", model="_mock::test-model"), prefix="/b"
+    )
+    # url_path_for resolves each agent's chat route by its unique name.
+    assert app.url_path_for("a_chat", session_id="x") == "/a/sessions/x/chat"
+    assert app.url_path_for("b_chat", session_id="x") == "/b/sessions/x/chat"
+
+
+def test_sessions_disabled_omits_session_routes():
+    """sessions=False drops the /sessions routes but keeps info/health/schema."""
+    app = FastAPI()
+    app.include_router(
+        create_router(_RouterTestAgent, model="_mock::test-model", sessions=False),
+        prefix=PREFIX,
+    )
+    client = TestClient(app)
+    assert client.get(f"{PREFIX}/health").json() == {"status": "ok"}
+    assert client.post(f"{PREFIX}/sessions").status_code == 404
+    assert client.get(f"{PREFIX}/sessions").status_code == 404
+
+
+def test_jobs_router_and_orchestrator_exposed():
+    """jobs=True mounts /jobs and exposes the orchestrator on the router."""
+    router = create_router(_RouterTestAgent, model="_mock::test-model", jobs=True)
+    assert router.orchestrator is not None
+    paths = {getattr(r, "path", None) for r in router.routes}
+    assert "/jobs" in paths
+    # Without jobs, no orchestrator.
+    plain = create_router(_RouterTestAgent, model="_mock::test-model")
+    assert plain.orchestrator is None
+
+
+def test_sessions_off_jobs_on():
+    """sessions=False with jobs=True serves an async-only agent."""
+    router = create_router(
+        _RouterTestAgent, model="_mock::test-model", sessions=False, jobs=True
+    )
+    paths = {getattr(r, "path", None) for r in router.routes}
+    assert "/jobs" in paths
+    assert "/sessions" not in paths