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.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
"""
File: /brains.py
Created Date: Monday December 1st 2025
Author: Christian Nonis <[email protected]>
-----
Last Modified: Wednesday March 4th 2026 9:35:41 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
import json
import os
from email import policy
from email.parser import BytesParser
from fastapi import Request
from starlette.middleware.base import BaseHTTPMiddleware
from starlette import status
from src.services.api.console_static import is_console_path
from src.services.api.errors import error_response
from src.services.data.main import data_adapter
from src.services.kg_agent.main import cache_adapter
def _brain_id_from_multipart(body: bytes, content_type: str) -> str | None:
try:
message_bytes = (
f"Content-Type: {content_type}\r\n\r\n".encode("utf-8", errors="replace")
+ body
)
msg = BytesParser(policy=policy.HTTP).parsebytes(message_bytes)
for part in msg.iter_parts():
if part.get_content_disposition() != "form-data":
continue
name = part.get_param("name", header="content-disposition")
if name == "brain_id":
raw = part.get_content_text()
return raw.rstrip() if raw else None
except Exception:
pass
return None
class BrainMiddleware(BaseHTTPMiddleware):
excluded_prefixes: set[str] = {"/console", "/docs", "/redoc", "/demo"}
brain_exempt_paths: set[str] = {
"/health",
"/openapi.json",
"/meta/login-info",
}
async def dispatch(self, request: Request, call_next):
if is_console_path(request.url.path):
return await call_next(request)
if any(request.url.path.startswith(p) for p in self.excluded_prefixes):
return await call_next(request)
if request.url.path in self.brain_exempt_paths:
return await call_next(request)
brainpat = request.headers.get("BrainPAT")
authorization = request.headers.get("Authorization", "")
if not brainpat and not authorization.lower().startswith("bearer "):
# Authentication middleware owns the missing-credential response. Avoid
# touching a backing store before it can return a structured 401.
return await call_next(request)
async def _get_brain_id():
brain_id = None
brain_id = request.headers.get("X-Brain-ID")
if brain_id:
brain_id = brain_id.rstrip()
if brain_id is None:
brain_id = request.query_params.get("brain_id")
if brain_id:
brain_id = brain_id.rstrip()
if brain_id is None and request.method in ("POST", "PUT", "PATCH"):
content_type = request.headers.get("content-type", "") or ""
body = await request.body()
if "application/json" in content_type and body:
try:
body_data = json.loads(body)
if isinstance(body_data, dict):
brain_id = body_data.get("brain_id")
if brain_id:
brain_id = brain_id.rstrip()
except (json.JSONDecodeError, ValueError):
pass
elif "multipart/form-data" in content_type and body:
form_brain_id = _brain_id_from_multipart(body, content_type)
if form_brain_id:
brain_id = form_brain_id
body_sent = [False]
async def receive():
if not body_sent[0]:
body_sent[0] = True
return {"type": "http.request", "body": body, "more_body": False}
return {"type": "http.request", "body": b"", "more_body": False}
request._receive = receive
request.state.brain_id = brain_id
return brain_id
# Variables ----------------------------------------------
brain_id = await _get_brain_id()
brain_creation_allowed = os.getenv("BRAIN_CREATION_ALLOWED") == "true"
default_brain_fallback = os.getenv("DEFAULT_BRAIN_FALLBACK") == "true"
# Bypassing system routes --------------------------------
if request.url.path.startswith("/system") or request.url.path == "/":
return await call_next(request)
# Cleanup checks -----------------------------------------
if brain_id == "system":
return error_response(
request,
status_code=status.HTTP_400_BAD_REQUEST,
detail="System brain is not allowed to be used.",
code="BRAIN_ID_RESERVED",
message="The system brain is reserved.",
resolution="Select a non-system application brain.",
)
if brain_id and not brain_id.isalnum():
return error_response(
request,
status_code=status.HTTP_400_BAD_REQUEST,
detail="Brain ID must be alphanumeric.",
code="BRAIN_ID_INVALID",
message="The brain identifier is invalid.",
resolution="Use an alphanumeric X-Brain-ID value.",
extra={"value": brain_id},
)
try:
cached_brain_id = cache_adapter.get(
key=f"brain:{brain_id}", brain_id="system"
)
if brain_id and not cached_brain_id:
stored_brain = data_adapter.get_brain(name_key=brain_id)
request.state.brain_id = brain_id
if not stored_brain and brain_creation_allowed:
new_brain = data_adapter.create_brain(name_key=brain_id)
cache_adapter.set(
key=f"brain:{brain_id}",
value=new_brain.id,
brain_id="system",
)
elif stored_brain:
cache_adapter.set(
key=f"brain:{brain_id}",
value=stored_brain.id,
brain_id="system",
)
elif not brain_id and default_brain_fallback:
default_brain = data_adapter.get_brain(name_key="default")
if not default_brain:
default_brain = data_adapter.create_brain(name_key="default")
cache_adapter.set(
key="brain:default",
value=default_brain.id,
brain_id="system",
)
request.state.brain_id = "default"
else:
cache_adapter.set(
key="brain:default",
value=default_brain.id,
brain_id="system",
)
request.state.brain_id = "default"
except Exception:
return error_response(
request,
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="Database unavailable. Check MongoDB connection and credentials (e.g. MONGO_* or MONGO_CONNECTION_STRING).",
)
if getattr(request.state, "brain_id", None) is None:
return error_response(
request,
status_code=status.HTTP_406_NOT_ACCEPTABLE,
detail="Brain not found or creation is not allowed.",
)
return await call_next(request)