ciridae 0.1.0__tar.gz

ciridae-0.1.0/.gitignore

@@ -0,0 +1 @@
+/_editable/

ciridae-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: ciridae
+Version: 0.1.0
+Summary: Public Python clients, models, and project utilities for Ciridae
+Project-URL: Repository, https://github.com/ciridae-ai/ciridae
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# Ciridae
+
+Public Python clients, models, and project utilities consumed by Ciridae
+services, standalone projects, and templates.
+
+The domain libraries remain the source owners in `libs/auth-client`,
+`libs/mcp-access`, and `libs/project-contract`. This directory only assembles
+their `ciridae.*` namespaces into one public distribution.
+
+`public-package-files.txt` is the reviewed artifact boundary. Adding any source
+file under an owned namespace fails the build until that file is explicitly
+added to the manifest.
+
+The PyPI distribution is `ciridae`. Import from the relevant domain namespace:
+
+```python
+from ciridae.auth import AuthServiceAccessResponse, AuthServiceClient
+from ciridae.mcp import CiridaeMcpClient, ProjectToolInventoryResponse
+from ciridae.project import ProjectDefinition
+```
+
+Validate a `project.yaml` file with the same packaged contract:
+
+```console
+ciridae validate-project project.yaml
+```
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`.
+2. Merge the change to `main`.
+3. Push the matching tag, for example `ciridae-v0.1.0`.
+
+The tag publishes through PyPI Trusted Publishing. Releases are immutable;
+change the version rather than replacing an existing artifact.

ciridae-0.1.0/README.md

@@ -0,0 +1,35 @@
+# Ciridae
+
+Public Python clients, models, and project utilities consumed by Ciridae
+services, standalone projects, and templates.
+
+The domain libraries remain the source owners in `libs/auth-client`,
+`libs/mcp-access`, and `libs/project-contract`. This directory only assembles
+their `ciridae.*` namespaces into one public distribution.
+
+`public-package-files.txt` is the reviewed artifact boundary. Adding any source
+file under an owned namespace fails the build until that file is explicitly
+added to the manifest.
+
+The PyPI distribution is `ciridae`. Import from the relevant domain namespace:
+
+```python
+from ciridae.auth import AuthServiceAccessResponse, AuthServiceClient
+from ciridae.mcp import CiridaeMcpClient, ProjectToolInventoryResponse
+from ciridae.project import ProjectDefinition
+```
+
+Validate a `project.yaml` file with the same packaged contract:
+
+```console
+ciridae validate-project project.yaml
+```
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`.
+2. Merge the change to `main`.
+3. Push the matching tag, for example `ciridae-v0.1.0`.
+
+The tag publishes through PyPI Trusted Publishing. Releases are immutable;
+change the version rather than replacing an existing artifact.

ciridae-0.1.0/_sources/ciridae/auth/__init__.py

@@ -0,0 +1,23 @@
+"""Client and public models for the Ciridae Auth Service."""
+
+from ciridae.auth.access import (
+    AuthServiceAccessResponse,
+    FirebaseUid,
+    FirebaseUidValue,
+)
+from ciridae.auth.api_error import (
+    AuthServiceApiError,
+    AuthServiceRejectedError,
+    AuthServiceUnavailableError,
+)
+from ciridae.auth.client import AuthServiceClient
+
+__all__ = [
+    "AuthServiceAccessResponse",
+    "AuthServiceApiError",
+    "AuthServiceClient",
+    "AuthServiceRejectedError",
+    "AuthServiceUnavailableError",
+    "FirebaseUid",
+    "FirebaseUidValue",
+]

ciridae-0.1.0/_sources/ciridae/auth/access.py

@@ -0,0 +1,23 @@
+"""Auth Service access-check response consumed by project backends."""
+
+from __future__ import annotations
+
+from typing import Annotated, ClassVar, NewType
+
+from pydantic import BaseModel, ConfigDict, StringConstraints
+
+FirebaseUid = NewType("FirebaseUid", str)
+FirebaseUidValue = Annotated[
+    FirebaseUid,
+    StringConstraints(min_length=1, strip_whitespace=True),
+]
+
+
+class AuthServiceAccessResponse(BaseModel):
+    """Result of verifying one bearer against a project's Auth realm."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", frozen=True)
+
+    has_access: bool
+    user_id: FirebaseUidValue | None
+    email: str | None

ciridae-0.1.0/_sources/ciridae/auth/api_error.py

@@ -0,0 +1,22 @@
+"""Auth Service client error."""
+
+
+class AuthServiceApiError(RuntimeError):
+    """Raised when an Auth Service request does not complete successfully."""
+
+    def __init__(self, *, status_code: int | None = None) -> None:
+        """Record whether the Auth Service returned an HTTP status.
+
+        Args:
+            status_code: The response status, or ``None`` for a transport failure.
+        """
+        super().__init__("Auth Service request failed")
+        self.status_code: int | None = status_code
+
+
+class AuthServiceRejectedError(AuthServiceApiError):
+    """Raised when the Auth Service definitively rejects a request."""
+
+
+class AuthServiceUnavailableError(AuthServiceApiError):
+    """Raised when no trustworthy Auth Service response is available."""

ciridae-0.1.0/_sources/ciridae/auth/client.py

@@ -0,0 +1,76 @@
+"""HTTP client for the Ciridae Auth Service."""
+
+from typing import Literal
+
+import httpx
+
+from ciridae.auth.api_error import (
+    AuthServiceRejectedError,
+    AuthServiceUnavailableError,
+)
+
+
+class AuthServiceClient(httpx.AsyncClient):
+    """Async client bound to one Auth Service endpoint and service API key."""
+
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        api_key: str,
+        timeout: float | httpx.Timeout,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Configure the Auth Service URL, bearer, and transport policy.
+
+        Args:
+            api_url: Auth Service API root.
+            api_key: Project-scoped service API key.
+            timeout: HTTPX timeout policy for Auth Service requests.
+            transport: Optional transport override for boundary tests.
+        """
+        super().__init__(
+            base_url=api_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+            follow_redirects=False,
+            trust_env=False,
+            transport=transport,
+        )
+
+    async def request_success(
+        self,
+        method: Literal["GET", "POST", "DELETE"],
+        path: str,
+        *,
+        params: dict[str, str | int] | None = None,
+        json: dict[str, object] | None = None,
+    ) -> httpx.Response:
+        """Make one request and return only a definite 2xx response.
+
+        Args:
+            method: HTTP method.
+            path: Path relative to the configured Auth Service API root.
+            params: Optional query parameters.
+            json: Optional JSON request body.
+
+        Returns:
+            The successful Auth Service response.
+
+        Raises:
+            AuthServiceApiError: If transport fails or the service returns a
+                non-2xx status.
+        """
+        try:
+            response = await self.request(method, path, params=params, json=json)
+        except httpx.RequestError:
+            # Leave the exception boundary before raising: RequestError retains
+            # its request, whose headers carry the bearer.
+            response = None
+        if response is None:
+            raise AuthServiceUnavailableError
+        if response.is_success:
+            return response
+        if response.is_server_error:
+            raise AuthServiceUnavailableError(status_code=response.status_code)
+        raise AuthServiceRejectedError(status_code=response.status_code)

ciridae-0.1.0/_sources/ciridae/auth/py.typed

@@ -0,0 +1 @@
+

ciridae-0.1.0/_sources/ciridae/mcp/__init__.py

@@ -0,0 +1,45 @@
+"""Client and public models for Ciridae MCP project access."""
+
+from ciridae.mcp.access import (
+    DEFAULT_MCP_ACCESS_MODE,
+    ConnectCode,
+    ConnectUserId,
+    McpAccessCategoryMode,
+    McpAccessMode,
+)
+from ciridae.mcp.api_error import CiridaeMcpApiError
+from ciridae.mcp.client import (
+    CiridaeMcpClient,
+    fetch_project_tool_inventory,
+    mint_connect_link,
+)
+from ciridae.mcp.connect_link import ConnectLink
+from ciridae.mcp.project_tool_inventory import (
+    AvailableProjectToolInventoryResponse,
+    ProjectToolInventoryItemResponse,
+    ProjectToolInventoryResponse,
+    UnavailableProjectToolInventoryResponse,
+)
+from ciridae.mcp.tool_operation import HttpMethod, ToolOperation
+from ciridae.project import ProjectId, ProjectIdValue
+
+__all__ = [
+    "DEFAULT_MCP_ACCESS_MODE",
+    "AvailableProjectToolInventoryResponse",
+    "CiridaeMcpApiError",
+    "CiridaeMcpClient",
+    "ConnectCode",
+    "ConnectLink",
+    "ConnectUserId",
+    "HttpMethod",
+    "McpAccessCategoryMode",
+    "McpAccessMode",
+    "ProjectId",
+    "ProjectIdValue",
+    "ProjectToolInventoryItemResponse",
+    "ProjectToolInventoryResponse",
+    "ToolOperation",
+    "UnavailableProjectToolInventoryResponse",
+    "fetch_project_tool_inventory",
+    "mint_connect_link",
+]

ciridae-0.1.0/_sources/ciridae/mcp/access.py

@@ -0,0 +1,26 @@
+"""Access vocabulary shared with the Ciridae MCP gateway."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+ConnectCode = Annotated[
+    str,
+    Field(
+        min_length=1,
+        description="Single-use code pasted at the gateway's consent screen.",
+    ),
+]
+ConnectUserId = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=128,
+        description="User ID the minted connect link will act as.",
+    ),
+]
+McpAccessMode = Literal["read_only", "all", "selected"]
+McpAccessCategoryMode = Literal["read_only", "all"]
+DEFAULT_MCP_ACCESS_MODE: McpAccessMode = "read_only"

ciridae-0.1.0/_sources/ciridae/mcp/api_error.py

@@ -0,0 +1,25 @@
+"""Custom exception type raised by Ciridae MCP gateway calls."""
+
+from __future__ import annotations
+
+
+class CiridaeMcpApiError(RuntimeError):
+    """Raised when a Ciridae MCP gateway call cannot complete successfully.
+
+    Covers a gateway that never answered as well as one that answered wrongly,
+    because every caller handles the two the same way.
+
+    Attributes:
+        status_code: The status the gateway returned, or `None` when the
+            failure happened before a response arrived.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        """Build a `CiridaeMcpApiError`.
+
+        Args:
+            message: Human-readable description of the failure.
+            status_code: The status the gateway returned, if it answered.
+        """
+        super().__init__(message)
+        self.status_code: int | None = status_code

ciridae-0.1.0/_sources/ciridae/mcp/client.py

@@ -0,0 +1,211 @@
+"""HTTP client for the Ciridae MCP gateway."""
+
+from __future__ import annotations
+
+import logging
+from http import HTTPStatus
+
+import httpx
+from ciridae.mcp.access import ConnectUserId, McpAccessMode
+from ciridae.mcp.api_error import CiridaeMcpApiError
+from ciridae.mcp.connect_link import ConnectLink
+from ciridae.mcp.endpoint import CiridaeMcpApiRoot
+from ciridae.mcp.project_tool_inventory import ProjectToolInventoryResponse
+from ciridae.mcp.tool_operation import ToolOperation
+from ciridae.project import ProjectId
+from pydantic import SecretStr, TypeAdapter, ValidationError
+
+logger = logging.getLogger(__name__)
+
+# Bound both local gateway work and downstream project-catalog reads.
+_DEFAULT_TIMEOUT_SECONDS = 30.0
+_PROJECT_TOOL_INVENTORY_ADAPTER: TypeAdapter[ProjectToolInventoryResponse] = (
+    TypeAdapter(ProjectToolInventoryResponse)
+)
+
+
+class CiridaeMcpClient(httpx.AsyncClient):
+    """Async client bound to one Ciridae MCP gateway and management key."""
+
+    def __init__(
+        self,
+        *,
+        api_root: CiridaeMcpApiRoot,
+        management_key: SecretStr,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Configure the fixed gateway URL, bearer, and transport policy.
+
+        Args:
+            api_root: The gateway API root; `to_api_root` derives this from a
+                validated `CIRIDAE_MCP_ENDPOINT`.
+            management_key: The project endpoint-scoped management key.
+            transport: Optional transport override for boundary tests.
+        """
+        super().__init__(
+            base_url=api_root,
+            timeout=_DEFAULT_TIMEOUT_SECONDS,
+            headers={"Authorization": f"Bearer {management_key.get_secret_value()}"},
+            # Both are about where the bearer can end up. httpx already
+            # defaults to not following redirects; stated here because a
+            # redirect the gateway did not author would carry the header to
+            # whatever host it named. `trust_env=False` is the one that
+            # changes behaviour: it stops HTTPS_PROXY from putting a third
+            # party on the path of every mint.
+            follow_redirects=False,
+            trust_env=False,
+            transport=transport,
+        )
+
+
+async def fetch_project_tool_inventory(
+    client: CiridaeMcpClient,
+    *,
+    expected_project_id: ProjectId,
+) -> ProjectToolInventoryResponse:
+    """Fetch the compiled inventory authorized by a project's management key.
+
+    Args:
+        client: The client bound to this deployment's gateway and bearer.
+        expected_project_id: The canonical project the caller expects the key
+            to select.
+
+    Returns:
+        The gateway's available or explicitly unavailable inventory.
+
+    Raises:
+        CiridaeMcpApiError: If the gateway cannot be reached, rejects the
+            request, answers unreadably, or selects a different project.
+    """
+    try:
+        response = await client.get("/v1/tools")
+    except httpx.RequestError:
+        # `from None`: `RequestError.request.headers` carries the bearer.
+        msg = "Ciridae MCP could not be reached"
+        raise CiridaeMcpApiError(msg) from None
+    if response.status_code != HTTPStatus.OK:
+        # No body: a rejection can echo the request.
+        logger.warning(
+            "Ciridae MCP tool inventory failed with status %s", response.status_code
+        )
+        msg = f"Ciridae MCP refused the tool inventory (status={response.status_code})"
+        raise CiridaeMcpApiError(msg, status_code=response.status_code)
+    try:
+        # The gateway owns this response and may add metadata before every
+        # consumer deploys. Keep the producer model closed while making this
+        # cross-service read boundary forward-compatible with additive fields.
+        inventory = _PROJECT_TOOL_INVENTORY_ADAPTER.validate_json(
+            response.content,
+            extra="ignore",
+        )
+    except ValidationError:
+        # The validation error may quote the upstream body.
+        msg = "Ciridae MCP returned a tool inventory that could not be read"
+        raise CiridaeMcpApiError(msg) from None
+    if inventory.project_id != expected_project_id:
+        msg = "Ciridae MCP returned a tool inventory for a different project"
+        raise CiridaeMcpApiError(msg)
+    return inventory
+
+
+async def mint_connect_link(
+    client: CiridaeMcpClient,
+    *,
+    user_id: ConnectUserId,
+    access: McpAccessMode,
+    tools: tuple[ToolOperation, ...] | None = None,
+) -> ConnectLink:
+    """Mint a connect link the named user can redeem in an MCP client.
+
+    The management key is the whole authorization; the gateway does not
+    re-check membership, so passing an authenticated UID is a caller
+    obligation.
+
+    Args:
+        client: The client bound to this deployment's gateway and bearer.
+        user_id: User id of the member the link will act as.
+        access: The access the redeemed connection is granted.
+        tools: The exact operations granted when ``access`` is ``selected``;
+            the gateway refuses any other pairing.
+
+    Returns:
+        The minted link. Its URL is visible only in this response.
+
+    Raises:
+        CiridaeMcpApiError: If the gateway cannot be reached, rejects the
+            request, or answers with an unreadable link or one bound to a
+            different user or access mode.
+    """
+    payload: dict[str, object] = {"user_id": user_id, "access": access}
+    if tools is not None:
+        payload["tools"] = [
+            {
+                "method": operation.method,
+                "path_template": operation.path_template,
+            }
+            for operation in tools
+        ]
+    try:
+        response = await client.post("/v1/connect-links", json=payload)
+    except httpx.RequestError:
+        # `from None`: `RequestError.request.headers` carries the bearer.
+        msg = "Ciridae MCP could not be reached"
+        raise CiridaeMcpApiError(msg) from None
+    _raise_for_status_or_error(response)
+    link = _parse_link(response.content)
+    if link is None:
+        msg = "Ciridae MCP returned a connect link that could not be read"
+        raise CiridaeMcpApiError(msg)
+    if (
+        link.user_id != user_id
+        or link.access != access
+        or _selection_set(link.tools) != _selection_set(tools)
+    ):
+        msg = "Ciridae MCP minted a connect link for a different grant"
+        raise CiridaeMcpApiError(msg)
+    return link
+
+
+def _selection_set(
+    tools: tuple[ToolOperation, ...] | None,
+) -> frozenset[ToolOperation] | None:
+    """Compare selections by membership; order on the wire is not semantic.
+
+    Returns:
+        The selection as a set, or ``None`` when no selection was made.
+    """
+    return None if tools is None else frozenset(tools)
+
+
+def _raise_for_status_or_error(response: httpx.Response) -> None:
+    """Return for a 2xx mint response, otherwise raise.
+
+    Args:
+        response: The gateway's mint response.
+
+    Raises:
+        CiridaeMcpApiError: For any non-2xx status.
+    """
+    if HTTPStatus.OK <= response.status_code < HTTPStatus.MULTIPLE_CHOICES:
+        return
+    # No body: a rejection can echo the request or carry a signed URL.
+    logger.warning("Ciridae MCP mint failed with status %s", response.status_code)
+    msg = f"Ciridae MCP rejected mint (status={response.status_code})"
+    raise CiridaeMcpApiError(msg, status_code=response.status_code)
+
+
+def _parse_link(content: bytes) -> ConnectLink | None:
+    """Parse a `ConnectLink` from a gateway response body.
+
+    Args:
+        content: The raw response body.
+
+    Returns:
+        The parsed link, or `None` when the body cannot be read. Returning
+        rather than raising keeps `ValidationError` (which quotes its input)
+        out of both `__cause__` and `__context__`.
+    """
+    try:
+        return ConnectLink.model_validate_json(content)
+    except ValidationError:
+        return None

ciridae-0.1.0/_sources/ciridae/mcp/connect_link.py

@@ -0,0 +1,36 @@
+"""Wire schema for a connect link returned by the Ciridae MCP gateway."""
+
+from __future__ import annotations
+
+from typing import ClassVar, Self
+
+from ciridae.mcp.access import ConnectCode, ConnectUserId, McpAccessMode
+from ciridae.mcp.tool_operation import ToolOperation
+from pydantic import AwareDatetime, BaseModel, ConfigDict, model_validator
+
+
+class ConnectLink(BaseModel):
+    """A single-use, expiring credential that connects one user's MCP client."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True)
+
+    code: ConnectCode
+    user_id: ConnectUserId
+    access: McpAccessMode
+    tools: tuple[ToolOperation, ...] | None = None
+    expires_at: AwareDatetime
+
+    @model_validator(mode="after")
+    def _selection_matches_the_access(self) -> Self:
+        """Require an exact operation list only for selected access.
+
+        Returns:
+            The validated connect link.
+
+        Raises:
+            ValueError: The access mode and tool selection disagree.
+        """
+        if (self.access == "selected") is not (self.tools is not None):
+            msg = f"access={self.access!r} does not match tools={self.tools!r}"
+            raise ValueError(msg)
+        return self