cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/__init__.py

@@ -0,0 +1,170 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Public API
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: PS-20 API toolkit for all Cloud-Dog Python services. Provides
+#   standard envelopes, error taxonomy, auth, CRUD, pagination, health,
+#   streaming, HTTP client, correlation, idempotency, CORS, timeout,
+#   OpenAPI, MCP/A2A gateways, test scaffolding, and an app factory.
+# Related requirements: SV1.1, SV1.2, FR17.1
+# Related architecture: SA1
+
+"""cloud_dog_api_kit — PS-20 API toolkit for Cloud-Dog services.
+
+Public API:
+    create_app(...)  — FastAPI app factory wiring all components.
+"""
+
+# ruff: noqa: E402
+
+from __future__ import annotations
+
+__version__ = "0.12.1"
+
+
+def create_app(*args, **kwargs):  # type: ignore[no-untyped-def]
+    """Import the app factory lazily so optional dependencies remain optional."""
+    try:
+        from cloud_dog_api_kit.factory import create_app as _create_app
+    except ModuleNotFoundError as exc:
+        if exc.name != "cloud_dog_logging":
+            raise
+        raise ModuleNotFoundError("create_app requires the optional 'cloud-dog-logging' dependency") from exc
+    return _create_app(*args, **kwargs)
+
+
+from cloud_dog_api_kit.a2a.events import (
+    ConfigChangeEvent,
+    EventBroadcaster,
+    HTTPIngestAdapter,
+    InMemoryEventBroadcaster,
+    PersistentEventBroadcaster,
+    RESTPollAdapter,
+    WebSocketAdapter,
+    create_a2a_events_router,
+)
+from cloud_dog_api_kit.compat import (
+    LegacyEnvelopeMiddleware,
+    LegacyRouteAdapter,
+    LegacyRouteAdapterMiddleware,
+    ProfileContextMiddleware,
+    legacy_envelope_route,
+)
+from cloud_dog_api_kit.correlation import CorrelationMiddleware
+from cloud_dog_api_kit.middleware import configure_cors
+from cloud_dog_api_kit.lifecycle import (
+    GracefulShutdownManager,
+    LifecycleHooks,
+    ShutdownDrainMiddleware,
+    install_shutdown_signal_handlers,
+)
+from cloud_dog_api_kit.mcp import (
+    MCPContractRegistration,
+    McpSessionManager,
+    ToolContract,
+    map_legacy_mcp_payload,
+    register_mcp_contract,
+    register_mcp_routes,
+    register_tool_router,
+)
+from cloud_dog_api_kit.envelopes import (
+    ErrorDetail,
+    ErrorResponse,
+    Meta,
+    SuccessResponse,
+    error_envelope,
+    success_envelope,
+)
+from cloud_dog_api_kit.schemas.pagination import PageInfo, PaginatedData, paginated_envelope
+from cloud_dog_api_kit.errors import (
+    APIError,
+    ConflictError,
+    InternalError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    UnauthenticatedError,
+    UnauthorisedError,
+    UpstreamError,
+    ValidationError,
+    register_error_handlers,
+)
+from cloud_dog_api_kit.routers.health import HealthCheck, create_health_router
+from cloud_dog_api_kit.middleware import RequestLoggingMiddleware, RequestSizeLimitMiddleware
+from cloud_dog_api_kit.openapi import configure_openapi
+from cloud_dog_api_kit.versioning import VersionHeaderMiddleware
+from cloud_dog_api_kit.webhook import WebhookSignatureMiddleware, compute_webhook_signature
+from cloud_dog_api_kit.web.proxy import WebApiProxy
+
+__all__ = [
+    "create_app",
+    "APIError",
+    "ConfigChangeEvent",
+    "ConflictError",
+    "EventBroadcaster",
+    "HTTPIngestAdapter",
+    "InMemoryEventBroadcaster",
+    "PersistentEventBroadcaster",
+    "RESTPollAdapter",
+    "WebSocketAdapter",
+    "create_a2a_events_router",
+    "InternalError",
+    "NotFoundError",
+    "RateLimitError",
+    "TimeoutError",
+    "UnauthenticatedError",
+    "UnauthorisedError",
+    "UpstreamError",
+    "ValidationError",
+    "GracefulShutdownManager",
+    "ErrorDetail",
+    "ErrorResponse",
+    "LegacyEnvelopeMiddleware",
+    "LegacyRouteAdapter",
+    "LegacyRouteAdapterMiddleware",
+    "LifecycleHooks",
+    "MCPContractRegistration",
+    "Meta",
+    "McpSessionManager",
+    "PageInfo",
+    "PaginatedData",
+    "ProfileContextMiddleware",
+    "RequestSizeLimitMiddleware",
+    "ShutdownDrainMiddleware",
+    "SuccessResponse",
+    "ToolContract",
+    "WebhookSignatureMiddleware",
+    "compute_webhook_signature",
+    "error_envelope",
+    "install_shutdown_signal_handlers",
+    "legacy_envelope_route",
+    "map_legacy_mcp_payload",
+    "paginated_envelope",
+    "register_mcp_contract",
+    "register_mcp_routes",
+    "success_envelope",
+    "register_tool_router",
+    "register_error_handlers",
+    "HealthCheck",
+    "create_health_router",
+    "CorrelationMiddleware",
+    "RequestLoggingMiddleware",
+    "VersionHeaderMiddleware",
+    "configure_cors",
+    "configure_openapi",
+    "WebApiProxy",
+]

cloud_dog_api_kit/a2a/__init__.py

@@ -0,0 +1,53 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — A2A gateway
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: REST-to-A2A gateway helpers.
+# Related requirements: FR15.1
+# Related architecture: SA1
+
+"""A2A gateway helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.a2a.card import A2ASkill, create_a2a_card_router
+from cloud_dog_api_kit.a2a.events import (
+    ConfigChangeEvent,
+    EventBroadcaster,
+    HTTPIngestAdapter,
+    InMemoryEventBroadcaster,
+    PersistentEventBroadcaster,
+    RESTPollAdapter,
+    WebSocketAdapter,
+    create_a2a_events_router,
+)
+from cloud_dog_api_kit.a2a.gateway import A2AHandler, create_a2a_handler_from_endpoint
+
+__all__ = [
+    "A2AHandler",
+    "A2ASkill",
+    "ConfigChangeEvent",
+    "EventBroadcaster",
+    "HTTPIngestAdapter",
+    "InMemoryEventBroadcaster",
+    "PersistentEventBroadcaster",
+    "RESTPollAdapter",
+    "WebSocketAdapter",
+    "create_a2a_card_router",
+    "create_a2a_events_router",
+    "create_a2a_handler_from_endpoint",
+]

cloud_dog_api_kit/a2a/card.py

@@ -0,0 +1,138 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""A2A agent card and task submission router.
+
+Provides ``create_a2a_card_router`` which adds:
+- ``GET /.well-known/agent.json`` — agent card per A2A protocol spec
+- ``POST /a2a/tasks`` — task submission that routes to skill handlers
+
+Usage in any service's A2A server::
+
+    from cloud_dog_api_kit.a2a.card import create_a2a_card_router, A2ASkill
+
+    skills = [
+        A2ASkill(id="search", name="Search", description="Semantic search",
+                 handler=lambda text: service.search(query=text)),
+    ]
+    router = create_a2a_card_router(
+        name="index-retriever",
+        description="Vector database search and document ingestion",
+        url="https://example.invalid/a2a",
+        skills=skills,
+    )
+    app.include_router(router)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from uuid import uuid4
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+
+@dataclass
+class A2ASkill:
+    """A skill exposed via the A2A agent card."""
+
+    id: str
+    name: str
+    description: str
+    handler: Callable[[str], Any] | None = None
+
+
+def create_a2a_card_router(
+    *,
+    name: str,
+    description: str,
+    url: str = "",
+    version: str = "1.0.0",
+    skills: list[A2ASkill] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router with A2A agent card and task submission.
+
+    Args:
+        name: Service name for the agent card.
+        description: Human-readable service description.
+        url: Base URL for the A2A endpoint.
+        version: Service version string.
+        skills: List of skills to expose. Each skill can have a handler
+            function that accepts a text input and returns a result.
+
+    Returns:
+        A FastAPI APIRouter with agent card and task routes.
+    """
+    _skills = skills or []
+    _skill_map: dict[str, A2ASkill] = {s.id: s for s in _skills}
+
+    card = {
+        "name": name,
+        "description": description,
+        "url": url,
+        "version": version,
+        "capabilities": {"streaming": False, "pushNotifications": False},
+        "skills": [
+            {"id": s.id, "name": s.name, "description": s.description}
+            for s in _skills
+        ],
+    }
+
+    router = APIRouter()
+
+    @router.get("/.well-known/agent.json")
+    async def agent_card() -> JSONResponse:
+        """Return the A2A agent card as JSON."""
+        return JSONResponse(card)
+
+    @router.post("/a2a/tasks")
+    @router.post("/tasks")
+    async def submit_task(request: Request) -> JSONResponse:
+        """Accept an A2A task submission and dispatch to the matching skill."""
+        body = await request.json()
+        task_id = body.get("id", str(uuid4()))
+        skill_id = body.get("skill_id", "")
+        input_data = body.get("input", {})
+        input_text = input_data.get("text", "") if isinstance(input_data, dict) else str(input_data)
+
+        skill = _skill_map.get(skill_id)
+        if skill is None:
+            # If no specific skill, try a generic "health" skill
+            if skill_id == "health":
+                return JSONResponse({
+                    "id": task_id,
+                    "status": "completed",
+                    "output": {"type": "text", "text": f"{name} is healthy"},
+                })
+            return JSONResponse(
+                {"id": task_id, "status": "failed",
+                 "error": f"Unknown skill: {skill_id}. Available: {list(_skill_map.keys())}"},
+                status_code=404,
+            )
+
+        try:
+            if skill.handler is not None:
+                result = skill.handler(input_text)
+                # Handle async handlers
+                import asyncio
+                if asyncio.iscoroutine(result):
+                    result = await result
+                result_text = str(result)
+            else:
+                result_text = f"Skill '{skill_id}' acknowledged (no handler configured)"
+        except Exception as exc:
+            return JSONResponse({
+                "id": task_id,
+                "status": "failed",
+                "error": str(exc),
+            })
+
+        return JSONResponse({
+            "id": task_id,
+            "status": "completed",
+            "output": {"type": "text", "text": result_text},
+        })
+
+    return router