hai-agent-api 0.1.0__py3-none-any.whl

agent_api/__init__.py

@@ -0,0 +1,28 @@
+"""Shared FastAPI surface for the H Agent Platform agents API."""
+
+from agent_api.config import ApiConfig, AuthConfig
+from agent_api.routers import create_router
+from agent_api.services import Services
+from agent_api.services.protocols import (
+    AgentServiceProtocol,
+    EnvironmentServiceProtocol,
+    MemoryServiceProtocol,
+    SessionServiceProtocol,
+    SkillServiceProtocol,
+)
+from agent_api.user import ApiUser, OrgId, UserId
+
+__all__ = [
+    "AgentServiceProtocol",
+    "ApiConfig",
+    "AuthConfig",
+    "ApiUser",
+    "EnvironmentServiceProtocol",
+    "MemoryServiceProtocol",
+    "OrgId",
+    "Services",
+    "SessionServiceProtocol",
+    "SkillServiceProtocol",
+    "UserId",
+    "create_router",
+]

agent_api/config.py

@@ -0,0 +1,31 @@
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+DEFAULT_LOCAL_USER_ID = UUID("00000000-0000-0000-0000-000000000001")
+DEFAULT_LOCAL_ORG_ID = UUID("00000000-0000-0000-0000-000000000002")
+
+
+class AuthConfig(BaseModel):
+    """Authentication behavior for ``create_router``.
+
+    ``platform`` requires ``X-User-Sub`` and ``X-User-Org`` (as injected by the Agent Platform gateway).
+    ``local`` fills missing identity headers with ``default_user_id`` / ``default_org_id`` for protected routes.
+    """
+
+    mode: Literal["platform", "local"] = "platform"
+    default_user_id: UUID = Field(default=DEFAULT_LOCAL_USER_ID)
+    default_org_id: UUID = Field(default=DEFAULT_LOCAL_ORG_ID)
+    default_email: str = "local-dev@example.com"
+
+
+class ApiConfig(BaseModel):
+    """Runtime configuration for agents API routers."""
+
+    long_poll_max_wait_for_seconds: int = Field(default=60, ge=0)
+    session_share_url_template: str = Field(
+        default="/share/api/v1/trajectories/{session_id}",
+        description="Path template for public session share links; ``{session_id}`` is substituted.",
+    )
+    auth: AuthConfig = Field(default_factory=AuthConfig)

agent_api/deps/auth.py

@@ -0,0 +1,100 @@
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Annotated
+from uuid import UUID
+
+from agent_api.config import AuthConfig
+from agent_api.user import ApiUser
+from fastapi import Depends, Header, HTTPException, Security
+from fastapi.security import HTTPBearer
+
+logger = logging.getLogger(__name__)
+
+AuthenticateDep = Callable[..., Awaitable[ApiUser]]
+OptionalAuthenticateDep = Callable[..., Awaitable[ApiUser | None]]
+
+
+@dataclass(frozen=True)
+class AuthDeps:
+    """FastAPI dependencies wired into agents API routers."""
+
+    authenticate: AuthenticateDep
+    optional_authenticate: OptionalAuthenticateDep
+
+
+def _make_get_user(
+    *,
+    default_user_id: UUID | None = None,
+    default_org_id: UUID | None = None,
+    default_email: str = "",
+) -> Callable[..., ApiUser | None]:
+    def _get_user(
+        user_id: Annotated[str | None, Header(alias="X-User-Sub", include_in_schema=False)] = None,
+        org_id: Annotated[str | None, Header(alias="X-User-Org", include_in_schema=False)] = None,
+        role: Annotated[str | None, Header(alias="X-User-Role", include_in_schema=False)] = None,
+        org_role: Annotated[str | None, Header(alias="X-User-Org-Role", include_in_schema=False)] = None,
+        email: Annotated[str | None, Header(alias="X-User-Email", include_in_schema=False)] = None,
+        _: Annotated[HTTPBearer, Depends(HTTPBearer(auto_error=False))] = None,
+    ) -> ApiUser | None:
+        if default_user_id is not None and default_org_id is not None:
+            user_id = user_id or str(default_user_id)
+            org_id = org_id or str(default_org_id)
+            if email is None:
+                email = default_email
+        elif not user_id or not org_id:
+            return None
+
+        if email is None:
+            email = ""
+
+        try:
+            return ApiUser(id=UUID(user_id), org_id=UUID(org_id), role=role, org_role=org_role, email=email)
+        except ValueError:
+            logger.warning("Invalid UUID in auth headers: user_id=%s, org_id=%s", user_id, org_id)
+            raise HTTPException(status_code=HTTPStatus.BAD_REQUEST, detail="Invalid user or org ID") from None
+
+    return _get_user
+
+
+def _make_authenticate(get_user: Callable[..., ApiUser | None]) -> AuthenticateDep:
+    async def authenticate(user: Annotated[ApiUser | None, Security(get_user)]) -> ApiUser:
+        """Extract and validate the authenticated user."""
+        if user is None:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        return user
+
+    return authenticate
+
+
+def _make_optional_authenticate(get_user: Callable[..., ApiUser | None]) -> OptionalAuthenticateDep:
+    async def optional_authenticate(
+        user: Annotated[ApiUser | None, Security(get_user)],
+    ) -> ApiUser | None:
+        """Extract and validate the user when auth headers are present."""
+        return user
+
+    return optional_authenticate
+
+
+_platform_get_user = _make_get_user()
+authenticate = _make_authenticate(_platform_get_user)
+optional_authenticate = _make_optional_authenticate(_platform_get_user)
+PLATFORM_AUTH = AuthDeps(authenticate=authenticate, optional_authenticate=optional_authenticate)
+
+
+def build_auth_deps(config: AuthConfig) -> AuthDeps:
+    """Build router auth dependencies for the given configuration."""
+    if config.mode == "platform":
+        return PLATFORM_AUTH
+
+    get_user_with_defaults = _make_get_user(
+        default_user_id=config.default_user_id,
+        default_org_id=config.default_org_id,
+        default_email=config.default_email,
+    )
+    return AuthDeps(
+        authenticate=_make_authenticate(get_user_with_defaults),
+        optional_authenticate=optional_authenticate,
+    )

agent_api/deps/pagination.py

@@ -0,0 +1,31 @@
+from typing import Any, Callable, Coroutine, Literal
+
+from agp_types import PageRequest
+from fastapi import Query
+
+
+def page_requester(
+    sort_fields: list[str] | None = None, default_sort: list[str] | None = None
+) -> Callable[[], Coroutine[Any, Any, PageRequest]]:
+    """Build a FastAPI dependency that parses pagination query parameters."""
+    page_query = Query(1, ge=1, description="Page number (1-based)")
+    size_query = Query(10, ge=1, le=1000, description="Number of items per page")
+
+    if sort_fields:
+        SortField = Literal[tuple(sort_fields)]  # type: ignore[valid-type]
+
+        async def sorted_fn(
+            page: int = page_query,
+            size: int = size_query,
+            sort: list[SortField] | None = Query(default_sort, description="Sort by field"),  # type: ignore[valid-type]
+        ) -> PageRequest:
+            if sort is None and default_sort:
+                sort = default_sort
+            return PageRequest(page=page, size=size, sort=sort)
+
+        return sorted_fn
+
+    async def fn(page: int = page_query, size: int = size_query) -> PageRequest:
+        return PageRequest(page=page, size=size, sort=default_sort)
+
+    return fn

agent_api/exceptions.py

@@ -0,0 +1,5 @@
+KEY_MAX_LEN = 255
+
+
+class IdempotencyKeyConflict(Exception):
+    """Same Idempotency-Key, different request body."""

agent_api/models/__init__.py

@@ -0,0 +1,32 @@
+"""Module to describe the models."""
+
+from agent_api.models.memory import (
+    MAX_KEY_LENGTH,
+    MAX_NAMESPACE_LENGTH,
+    MAX_VALUE_BYTES,
+    CreateMemory,
+    MemoryRecord,
+    MemoryValue,
+    UpdateMemory,
+)
+from agent_api.models.quota import QuotaStatus
+from agent_api.models.requests import SessionEventsPageRequest, SessionsPageRequest
+from agent_api.models.session import SendMessage, Session, SessionSummary, ShareLink, UserMessageBatch
+
+__all__ = [
+    "CreateMemory",
+    "MAX_KEY_LENGTH",
+    "MAX_NAMESPACE_LENGTH",
+    "MAX_VALUE_BYTES",
+    "MemoryRecord",
+    "MemoryValue",
+    "QuotaStatus",
+    "SendMessage",
+    "Session",
+    "SessionEventsPageRequest",
+    "SessionSummary",
+    "SessionsPageRequest",
+    "ShareLink",
+    "UpdateMemory",
+    "UserMessageBatch",
+]

agent_api/models/memory.py

@@ -0,0 +1,45 @@
+"""Public API models for the Memory resource (per-org KV, scoped by namespace)."""
+
+from datetime import datetime
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import AfterValidator, BaseModel, Field
+
+MAX_NAMESPACE_LENGTH = 255
+MAX_KEY_LENGTH = 1024
+MAX_VALUE_BYTES = 65536
+
+
+def _cap_value_bytes(v: str) -> str:
+    if len(v.encode("utf-8")) > MAX_VALUE_BYTES:
+        raise ValueError(f"value exceeds {MAX_VALUE_BYTES}-byte cap")
+    return v
+
+
+MemoryValue = Annotated[str, AfterValidator(_cap_value_bytes)]
+
+
+class CreateMemory(BaseModel):
+    """Upsert a memory by ``(org_id, namespace, key)``."""
+
+    namespace: str = Field(..., min_length=1, max_length=MAX_NAMESPACE_LENGTH)
+    key: str = Field(..., min_length=1, max_length=MAX_KEY_LENGTH)
+    value: MemoryValue
+
+
+class UpdateMemory(BaseModel):
+    """Update a memory's value in place."""
+
+    value: MemoryValue
+
+
+class MemoryRecord(BaseModel):
+    """Persistent KV entry scoped to ``(org_id, namespace, key)``."""
+
+    id: UUID
+    namespace: str
+    key: str
+    value: str
+    created_at: datetime
+    updated_at: datetime

agent_api/models/quota.py

@@ -0,0 +1,12 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class QuotaStatus(BaseModel):
+    """Quota status."""
+
+    scope: Literal["user", "org"]
+    limit: int
+    active: int
+    available: int

agent_api/models/requests.py

@@ -0,0 +1,33 @@
+import datetime
+from typing import Literal
+
+from agp_types import PrivateScope, TrajectoryStatus
+from pydantic import BaseModel, Field
+
+
+class SessionsPageRequest(BaseModel):
+    """Page request for ``GET /v2/sessions``."""
+
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=10, ge=1, le=100)
+    sort: list[Literal["created_at", "-created_at"]] | None = None
+
+    owner: PrivateScope = "me-in-organization"
+    status: list[TrajectoryStatus] | None = None
+    agent: list[str] | None = None
+    group_id: str | None = None
+    parent_session_id: str | None = None
+    search: str | None = None
+    created_before: datetime.datetime | None = None
+    created_after: datetime.datetime | None = None
+    finished_before: datetime.datetime | None = None
+    finished_after: datetime.datetime | None = None
+
+
+class SessionEventsPageRequest(BaseModel):
+    """Page request for ``GET /v2/sessions/{id}/events``."""
+
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=50, ge=1, le=200)
+    sort: list[Literal["timestamp", "-timestamp"]] | None = None
+    type: str | None = None

agent_api/models/session.py

@@ -0,0 +1,68 @@
+"""Public ``Session`` models."""
+
+from datetime import datetime
+from typing import Annotated, Any, Literal
+from uuid import UUID
+
+from agent_interface import SessionStatus, TrajectoryStatus
+from agent_interface.definition import UserMessageEvent
+from agent_interface.specs.session import SessionRequest
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Session(BaseModel):
+    """Full session envelope: original request + live status."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    request: SessionRequest
+    status: SessionStatus
+    latest_answer: Any = Field(
+        default=None,
+        description=(
+            "The agent's most recent final answer: free-form text, or structured data when the "
+            "agent runs with a custom answer format. Null until the agent first answers. Mirrors the "
+            "answer streamed from the changes endpoint, surfaced here for non-interactive runs."
+        ),
+    )
+    created_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class SessionSummary(BaseModel):
+    """Flat projection for session listings, including child rosters via ``?parent_session_id=``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    agent: str | None = None
+    status: TrajectoryStatus
+    first_message: UserMessageEvent | None = None
+    created_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class UserMessageBatch(BaseModel):
+    """Batch of user messages."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["batch"] = "batch"
+    messages: Annotated[list[UserMessageEvent], Field(min_length=1)]
+
+
+SendMessage = Annotated[
+    UserMessageEvent | UserMessageBatch,
+    Field(discriminator="type"),
+]
+
+
+class ShareLink(BaseModel):
+    """Public share URL for a session."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    share_url: str

agent_api/routers/__init__.py

@@ -0,0 +1,29 @@
+"""Module to describe the routers."""
+
+from fastapi import APIRouter
+
+from agent_api.config import ApiConfig, AuthConfig
+from agent_api.deps.auth import build_auth_deps
+from agent_api.routers.agents import create_agents_router
+from agent_api.routers.environments import create_environments_router
+from agent_api.routers.memories import create_memories_router
+from agent_api.routers.sessions import create_sessions_router
+from agent_api.routers.skills import create_skills_router
+from agent_api.services import Services
+
+__all__ = ["ApiConfig", "AuthConfig", "Services", "create_router"]
+
+
+def create_router(services: Services, *, config: ApiConfig | None = None) -> APIRouter:
+    """Build the agents API router tree with versioned path prefixes."""
+    resolved_config = config or ApiConfig()
+    auth = build_auth_deps(resolved_config.auth)
+    v2 = APIRouter()
+    v2.include_router(create_sessions_router(services.sessions, resolved_config, auth), prefix="/sessions")
+    v2.include_router(create_memories_router(services.memories, auth), prefix="/memories", include_in_schema=False)
+    v2.include_router(create_skills_router(services.skills, auth), prefix="/skills")
+    v2.include_router(create_environments_router(services.environments, auth), prefix="/environments")
+    v2.include_router(create_agents_router(services.agents, auth), prefix="/agents")
+    router = APIRouter()
+    router.include_router(v2, prefix="/v2")
+    return router

agent_api/routers/agents.py

@@ -0,0 +1,75 @@
+"""Agent catalog endpoints."""
+
+from agent_interface.specs.agent import Agent
+from agp_types import Page, PageRequest
+from fastapi import APIRouter, Depends, Query
+from typing_extensions import Annotated
+
+from agent_api.deps.auth import PLATFORM_AUTH, AuthDeps
+from agent_api.deps.pagination import page_requester
+from agent_api.services.protocols import AgentServiceProtocol
+from agent_api.user import ApiUser
+
+
+def create_agents_router(service: AgentServiceProtocol, auth: AuthDeps = PLATFORM_AUTH) -> APIRouter:
+    """Create the agents router bound to ``service``."""
+    api = APIRouter(tags=["Agents"])
+
+    @api.post("", status_code=201)
+    async def create_agent(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        create: Agent,
+    ) -> Agent:
+        """Create an agent.."""
+        return await service.create_agent(user, create)
+
+    @api.get("")
+    async def list_agents(
+        page: Annotated[
+            PageRequest,
+            Depends(
+                page_requester(
+                    sort_fields=["created_at", "-created_at", "agent_name", "-agent_name"],
+                    default_sort=["-created_at"],
+                )
+            ),
+        ],
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        agent_name: Annotated[str | None, Query(description="Case-insensitive substring match on agent name.")] = None,
+        search: Annotated[str | None, Query(description="Case-insensitive match on agent name or description.")] = None,
+    ) -> Page[Agent]:
+        """List reserved + caller's org agents."""
+        return await service.get_page(user, page, agent_name=agent_name, search=search)
+
+    @api.get("/{agent_name:path}")
+    async def get_agent(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        agent_name: str,
+        resolve: Annotated[
+            bool, Query(description="Materialise string environment/skill/subagent leaves into full specs.")
+        ] = False,
+    ) -> Agent:
+        """Fetch by identifier; 404 if not visible. ``resolve=true`` materialises spec leaves."""
+        agent = await service.get_agent(user, agent_name)
+        if resolve:
+            agent = await service.resolve_agent_spec(user, agent)
+        return agent
+
+    @api.put("/{agent_name:path}")
+    async def update_agent(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        agent_name: str,
+        update: Agent,
+    ) -> Agent:
+        """Replace ``spec``. ``spec.name`` must match the URL identifier; renames are not supported."""
+        return await service.update_agent(user, agent_name, update)
+
+    @api.delete("/{agent_name:path}", status_code=204)
+    async def delete_agent(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        agent_name: str,
+    ) -> None:
+        """Delete by identifier. Reserved rows: H employee only."""
+        await service.delete_agent(user, agent_name)
+
+    return api

agent_api/routers/environments.py

@@ -0,0 +1,77 @@
+"""Environment catalog endpoints."""
+
+from agent_interface.specs.environment import Environment, EnvironmentKind
+from agp_types import Page, PageRequest
+from fastapi import APIRouter, Depends, Query
+from typing_extensions import Annotated
+
+from agent_api.deps.auth import PLATFORM_AUTH, AuthDeps
+from agent_api.deps.pagination import page_requester
+from agent_api.services.protocols import EnvironmentServiceProtocol
+from agent_api.user import ApiUser
+
+
+class EnvironmentPage(Page[Environment]):
+    """Named page subclass so OpenAPI emits a clean ``EnvironmentPage`` schema name."""
+
+
+def create_environments_router(service: EnvironmentServiceProtocol, auth: AuthDeps = PLATFORM_AUTH) -> APIRouter:
+    """Create the environments router bound to ``service``."""
+    api = APIRouter(tags=["Environments"])
+
+    @api.post("", status_code=201)
+    async def create_environment(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        create: Environment,
+    ) -> Environment:
+        """Create an environment."""
+        return await service.create_environment(user, create)
+
+    @api.get("")
+    async def list_environments(
+        page: Annotated[
+            PageRequest,
+            Depends(
+                page_requester(
+                    sort_fields=["created_at", "-created_at", "id", "-id"],
+                    default_sort=["-created_at"],
+                )
+            ),
+        ],
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: Annotated[str | None, Query(description="Case-insensitive substring match on environment id.")] = None,
+        kind: Annotated[EnvironmentKind | None, Query(description="Filter by environment kind.")] = None,
+        search: Annotated[
+            str | None, Query(description="Case-insensitive match on environment id or description.")
+        ] = None,
+    ) -> EnvironmentPage:
+        """List reserved + caller's org environments."""
+        result = await service.get_page(user, page, env_id=id, kind=kind, search=search)
+        return EnvironmentPage(items=result.items, total=result.total, page=result.page)
+
+    @api.get("/{id:path}")
+    async def get_environment(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: str,
+    ) -> Environment:
+        """Fetch by identifier; 404 if not visible. ``:path`` so slash-containing ids round-trip."""
+        return await service.get_environment(user, id)
+
+    @api.put("/{id:path}")
+    async def update_environment(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: str,
+        update: Environment,
+    ) -> Environment:
+        """Replace the environment spec."""
+        return await service.update_environment(user, id, update)
+
+    @api.delete("/{id:path}", status_code=204)
+    async def delete_environment(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: str,
+    ) -> None:
+        """Delete by identifier. Reserved rows: H employee only."""
+        await service.delete_environment(user, id)
+
+    return api

agent_api/routers/memories.py

@@ -0,0 +1,76 @@
+"""Memory API endpoints."""
+
+from uuid import UUID
+
+from agp_types import Page, PageRequest
+from fastapi import APIRouter, Depends, Query, Response
+from typing_extensions import Annotated
+
+from agent_api.deps.auth import PLATFORM_AUTH, AuthDeps
+from agent_api.deps.pagination import page_requester
+from agent_api.models.memory import CreateMemory, MemoryRecord, UpdateMemory
+from agent_api.services.protocols import MemoryServiceProtocol
+from agent_api.user import ApiUser
+
+
+def create_memories_router(service: MemoryServiceProtocol, auth: AuthDeps = PLATFORM_AUTH) -> APIRouter:
+    """Create the memories router bound to ``service``."""
+    api = APIRouter(tags=["Memories"])
+
+    @api.post(
+        "",
+        responses={
+            200: {"description": "Existing memory updated (upsert)."},
+            201: {"description": "New memory created."},
+        },
+    )
+    async def create_memory(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        create: CreateMemory,
+        response: Response,
+    ) -> MemoryRecord:
+        """Upsert a memory by ``(org_id, namespace, key)``. 201 on create, 200 on update."""
+        memory, created = await service.upsert_memory(user, create)
+        response.status_code = 201 if created else 200
+        return memory
+
+    @api.get("")
+    async def list_memories(
+        page: Annotated[
+            PageRequest,
+            Depends(page_requester(sort_fields=["updated_at", "-updated_at"], default_sort=["-updated_at"])),
+        ],
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        namespace: Annotated[str | None, Query(description="Exact namespace filter.")] = None,
+        key: Annotated[str | None, Query(description="Case-insensitive substring match on key.")] = None,
+        search: Annotated[str | None, Query(description="Case-insensitive match on key or value.")] = None,
+    ) -> Page[MemoryRecord]:
+        """List org memories; optional namespace, key, and text-search filters."""
+        return await service.get_page(user, page, namespace=namespace, key=key, search=search)
+
+    @api.get("/{id}")
+    async def get_memory(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: UUID,
+    ) -> MemoryRecord:
+        """Get a memory by id."""
+        return await service.get_memory(user, id)
+
+    @api.put("/{id}")
+    async def update_memory(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: UUID,
+        update: UpdateMemory,
+    ) -> MemoryRecord:
+        """Update a memory's value."""
+        return await service.update_memory(user, id, update)
+
+    @api.delete("/{id}", status_code=204)
+    async def delete_memory(
+        user: Annotated[ApiUser, Depends(auth.authenticate)],
+        id: UUID,
+    ) -> None:
+        """Delete a memory."""
+        await service.delete_memory(user, id)
+
+    return api