Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

7.6 KB
Raw Blame
"""OpenAPI guarantees for discovery and LLM function-calling clients."""

from __future__ import annotations

from typing import Any

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi


_HTTP_METHODS = {"get", "post", "put", "patch", "delete", "options", "head"}
_CORE_TAGS = {"public", "ingest", "retrieve", "model", "meta", "tasks", "system"}
_LIST_PATHS = {
    "/meta/entity-labels",
    "/meta/entity-properties",
    "/meta/relationships-properties",
    "/retrieve/hops",
    "/system/brains-list",
}


def _error_response(description: str) -> dict[str, Any]:
    return {
        "description": description,
        "content": {
            "application/json": {
                "schema": {"$ref": "#/components/schemas/ErrorResponse"}
            }
        },
    }


def install_openapi_contract(app: FastAPI) -> None:
    """Install a deterministic, fully-described OpenAPI schema builder."""

    def custom_openapi() -> dict[str, Any]:
        if app.openapi_schema is not None:
            return app.openapi_schema

        schema = get_openapi(
            title=app.title,
            version=app.version,
            openapi_version=app.openapi_version,
            description=app.description,
            routes=app.routes,
        )
        components = schema.setdefault("components", {})
        component_schemas = components.setdefault("schemas", {})
        security_schemes = components.setdefault("securitySchemes", {})
        security_schemes.update(
            {
                "BrainPAT": {
                    "type": "apiKey",
                    "in": "header",
                    "name": "BrainPAT",
                    "description": "BrainAPI personal access token.",
                },
                "BearerAuth": {
                    "type": "http",
                    "scheme": "bearer",
                    "description": "BrainAPI PAT sent as a Bearer token.",
                },
            }
        )

        protected_errors = {
            "400": _error_response("Invalid request"),
            "401": _error_response("Authentication failed"),
            "403": _error_response("Operation forbidden"),
            "404": _error_response("Resource not found"),
            "405": _error_response("Method not allowed"),
            "406": _error_response("Brain not found"),
            "422": _error_response("Validation failed"),
            "429": _error_response("Rate limit exceeded"),
            "500": _error_response("Internal service error"),
            "503": _error_response("Dependency unavailable"),
        }

        for path, path_item in schema.get("paths", {}).items():
            for method, operation in path_item.items():
                if method.lower() not in _HTTP_METHODS or not isinstance(operation, dict):
                    continue
                summary = operation.get("summary") or operation.get("operationId")
                if not operation.get("description"):
                    operation["description"] = (
                        f"{summary}. See the BrainAPI developer documentation for "
                        "request, response, authentication, and retry semantics."
                    )

                for status_code, response in operation.get("responses", {}).items():
                    if not str(status_code).startswith("2") or not isinstance(response, dict):
                        continue
                    for media in response.get("content", {}).values():
                        if isinstance(media, dict) and media.get("schema") == {}:
                            if _CORE_TAGS.intersection(operation.get("tags", [])):
                                raise ValueError(
                                    f"Core operation {method.upper()} {path} must define "
                                    "a typed success response model"
                                )
                            model = (
                                "GenericListResponse"
                                if path in _LIST_PATHS
                                else "GenericObjectResponse"
                            )
                            component_schemas.setdefault(
                                model,
                                (
                                    {
                                        "type": "array",
                                        "description": "A list of operation-specific JSON values.",
                                        "items": {
                                            "oneOf": [
                                                {"type": "string"},
                                                {
                                                    "type": "object",
                                                    "additionalProperties": True,
                                                },
                                            ]
                                        },
                                    }
                                    if model == "GenericListResponse"
                                    else {
                                        "type": "object",
                                        "description": (
                                            "An operation-specific JSON object from an "
                                            "installed extension."
                                        ),
                                        "additionalProperties": True,
                                    }
                                ),
                            )
                            media["schema"] = {
                                "$ref": f"#/components/schemas/{model}"
                            }

                is_public = path in {"/health", "/demo/search"}
                if is_public:
                    operation["security"] = []
                    public_errors = {
                        "405": _error_response("Method not allowed"),
                        "500": _error_response("Internal service error"),
                        "503": _error_response("Dependency unavailable"),
                    }
                    if path == "/demo/search":
                        public_errors.update(
                            {
                                "404": _error_response("Public demo disabled"),
                                "422": _error_response("Validation failed"),
                            }
                        )
                    responses = operation.setdefault("responses", {})
                    for code, response in public_errors.items():
                        if code == "422" or code not in responses:
                            responses[code] = response
                else:
                    operation["security"] = [{"BrainPAT": []}, {"BearerAuth": []}]
                    responses = operation.setdefault("responses", {})
                    for code, response in protected_errors.items():
                        if code == "422" or code not in responses:
                            responses[code] = response

                if path == "/demo/search":
                    operation.setdefault("responses", {})["429"] = _error_response(
                        "Public demo rate limit exceeded"
                    )
                    operation["x-rate-limit"] = {
                        "requests": 30,
                        "window": "60 seconds",
                    }

        schema["servers"] = [
            {"url": "http://localhost:8000", "description": "Local BrainAPI"}
        ]
        app.openapi_schema = schema
        return schema

    app.openapi = custom_openapi