10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/src/app/routers/media/router.py

@@ -0,0 +1,242 @@
+"""File upload, retrieval, and multimodal config endpoints."""
+
+from __future__ import annotations
+
+import mimetypes
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, UploadFile
+from fastapi.logger import logger
+from fastapi.responses import Response
+from injectq.integrations import InjectAPI
+
+from tenxgraph_api.src.app.core.auth.permissions import RequirePermission
+from tenxgraph_api.src.app.core.config.media_settings import get_media_settings
+from tenxgraph_api.src.app.routers.media import MediaService
+from tenxgraph_api.src.app.routers.media.schemas import (
+    FileAccessUrlResponse,
+    FileInfoResponse,
+    FileUploadResponse,
+    MultimodalConfigResponse,
+)
+from tenxgraph_api.src.app.utils import success_response
+
+
+router = APIRouter(tags=["Files"])
+
+# Read uploads in 1 MiB chunks so a size-cap breach is caught before the whole body
+# is buffered in memory.
+_UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+# Stored types come from the uploader. Only types a browser displays without running
+# script are served inline; the rest are downloads.
+_INLINE_TYPES = frozenset(
+    {
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/webp",
+        "image/avif",
+        "image/bmp",
+        "application/pdf",
+        "text/plain",
+    }
+)
+_INLINE_PREFIXES = ("audio/", "video/")
+
+
+def _is_active_type(mime: str) -> bool:
+    """Whether a browser would run this type as a page or script, even from a blob: URL.
+
+    Such files are served as opaque bytes, so neither a navigation nor ``response.blob()``
+    keeps the active type.
+    """
+    subtype = mime.partition("/")[2]
+    return (
+        subtype in {"html", "xml", "xhtml+xml", "svg+xml"}
+        or subtype.endswith("+xml")
+        or "javascript" in subtype
+        or "ecmascript" in subtype
+    )
+
+
+def _download_response(file_id: str, data: bytes, mime_type: str | None) -> Response:
+    """Serve stored bytes so an uploaded HTML or SVG file cannot run script on this origin."""
+    mime = (mime_type or "").split(";", 1)[0].strip().lower()
+    if mime in _INLINE_TYPES or mime.startswith(_INLINE_PREFIXES):
+        disposition = "inline"
+    else:
+        disposition = f'attachment; filename="{file_id}"'
+        if not mime or _is_active_type(mime):
+            mime = "application/octet-stream"
+    headers = {"Content-Disposition": disposition, "X-Content-Type-Options": "nosniff"}
+    if mime != "application/pdf":  # browsers will not render a PDF under a sandbox CSP
+        headers["Content-Security-Policy"] = "default-src 'none'; sandbox"
+    return Response(content=data, media_type=mime or "application/octet-stream", headers=headers)
+
+
+# ------------------------------------------------------------------
+# 4.1  POST /v1/files/upload
+# ------------------------------------------------------------------
+@router.post(
+    "/v1/files/upload",
+    summary="Upload a file (image, audio, document)",
+    response_model=FileUploadResponse,
+    description=(
+        "Accepts a multipart file upload.  Stores binary in the configured "
+        "MediaStore and optionally extracts text for documents."
+    ),
+)
+async def upload_file(
+    request: Request,
+    file: UploadFile,
+    service: MediaService = InjectAPI(MediaService),
+    user: dict[str, Any] = Depends(RequirePermission("files", "upload")),
+):
+    if file.filename is None:
+        raise HTTPException(status_code=400, detail="filename is required")
+
+    media_settings = get_media_settings()
+    mime = file.content_type or mimetypes.guess_type(file.filename)[0] or "application/octet-stream"
+
+    if not media_settings.is_content_type_allowed(mime):
+        raise HTTPException(status_code=415, detail=f"Content type not allowed: {mime}")
+
+    # Read with a running size cap instead of ``await file.read()``. A chunked upload
+    # (no Content-Length) slips past RequestSizeLimitMiddleware, so a naive full read
+    # would let a multi-GB body OOM-kill the worker. Stop as soon as we exceed the
+    # limit and reject, never materializing more than max_size + one chunk.
+    max_bytes = int(media_settings.MEDIA_MAX_SIZE_MB * 1024 * 1024)
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        chunk = await file.read(_UPLOAD_CHUNK_BYTES)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > max_bytes:
+            raise HTTPException(
+                status_code=413,
+                detail=f"File exceeds maximum {media_settings.MEDIA_MAX_SIZE_MB}MB",
+            )
+        chunks.append(chunk)
+    data = b"".join(chunks)
+    if not data:
+        raise HTTPException(status_code=400, detail="Empty file")
+
+    logger.info("File upload: %s (%s, %d bytes)", file.filename, mime, len(data))
+
+    try:
+        # Record the uploader as the owner, so the file cannot later be read by a
+        # different user who knows the id.
+        result = await service.upload_file(data, file.filename, mime, user_id=user.get("user_id"))
+    except ValueError as exc:
+        raise HTTPException(status_code=413, detail=str(exc))
+
+    return success_response(FileUploadResponse(**result), request)
+
+
+# ------------------------------------------------------------------
+# 4.2  GET /v1/files/{file_id}  — raw binary download
+# ------------------------------------------------------------------
+@router.get(
+    "/v1/files/{file_id}",
+    summary="Retrieve file binary",
+    description="Returns the raw binary with the correct Content-Type.",
+)
+async def get_file(
+    file_id: str,
+    service: MediaService = InjectAPI(MediaService),
+    user: dict[str, Any] = Depends(RequirePermission("files", "read")),
+):
+    try:
+        # Authentication alone is not enough: without this, ANY authenticated user
+        # who knew a file_id could download another user's file.
+        await service.ensure_can_access(file_id, user.get("user_id"))
+        data, mime_type = await service.get_file(file_id, user.get("user_id"))
+    except KeyError:
+        raise HTTPException(status_code=404, detail="File not found")
+    except PermissionError:
+        # 404, not 403: do not confirm that someone else's file_id exists.
+        raise HTTPException(status_code=404, detail="File not found")
+
+    return _download_response(file_id, data, mime_type)
+
+
+# ------------------------------------------------------------------
+# 4.2  GET /v1/files/{file_id}/info  — metadata only
+# ------------------------------------------------------------------
+@router.get(
+    "/v1/files/{file_id}/info",
+    summary="Retrieve file metadata",
+    response_model=FileInfoResponse,
+)
+async def get_file_info(
+    request: Request,
+    file_id: str,
+    service: MediaService = InjectAPI(MediaService),
+    user: dict[str, Any] = Depends(RequirePermission("files", "read")),
+):
+    try:
+        await service.ensure_can_access(file_id, user.get("user_id"))
+        info = await service.get_file_info(file_id, user.get("user_id"))
+    except KeyError:
+        raise HTTPException(status_code=404, detail="File not found")
+    except PermissionError:
+        raise HTTPException(status_code=404, detail="File not found")
+
+    return success_response(FileInfoResponse(**info), request)
+
+
+@router.get(
+    "/v1/files/{file_id}/url",
+    summary="Retrieve direct access URL",
+    response_model=FileAccessUrlResponse,
+)
+async def get_file_access_url(
+    request: Request,
+    file_id: str,
+    service: MediaService = InjectAPI(MediaService),
+    user: dict[str, Any] = Depends(RequirePermission("files", "read")),
+):
+    try:
+        # Especially important here: this hands out a *signed direct URL*, which
+        # bypasses the API entirely. Handing one to a non-owner would leak the file
+        # even after this check was added elsewhere.
+        await service.ensure_can_access(file_id, user.get("user_id"))
+        info = await service.get_file_info(file_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="File not found")
+    except PermissionError:
+        raise HTTPException(status_code=404, detail="File not found")
+
+    payload = FileAccessUrlResponse(
+        file_id=file_id,
+        url=info["direct_url"] or f"/v1/files/{file_id}",
+        expires_at=info.get("direct_url_expires_at"),
+        mime_type=info["mime_type"],
+    )
+    return success_response(payload, request)
+
+
+# ------------------------------------------------------------------
+# 4.4  GET /v1/config/multimodal  — read current multimodal config
+# ------------------------------------------------------------------
+@router.get(
+    "/v1/config/multimodal",
+    summary="Get multimodal configuration",
+    response_model=MultimodalConfigResponse,
+)
+async def get_multimodal_config(
+    request: Request,
+    user: dict[str, Any] = Depends(RequirePermission("config", "read")),
+):
+    settings = get_media_settings()
+    return success_response(
+        MultimodalConfigResponse(
+            media_storage_type=settings.MEDIA_STORAGE_TYPE.value,
+            media_max_size_mb=settings.MEDIA_MAX_SIZE_MB,
+            document_handling=settings.DOCUMENT_HANDLING,
+        ),
+        request,
+    )

tenxgraph_api/src/app/routers/media/schemas.py

@@ -0,0 +1,39 @@
+"""Schemas for the media / file upload endpoints."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class FileUploadResponse(BaseModel):
+    file_id: str = Field(..., description="Opaque storage key")
+    mime_type: str
+    size_bytes: int
+    filename: str
+    extracted_text: str | None = None
+    url: str = Field(..., description="Relative retrieval URL")
+    direct_url: str | None = None
+    direct_url_expires_at: int | None = None
+
+
+class FileInfoResponse(BaseModel):
+    file_id: str
+    mime_type: str
+    size_bytes: int
+    filename: str | None = None
+    extracted_text: str | None = None
+    direct_url: str | None = None
+    direct_url_expires_at: int | None = None
+
+
+class FileAccessUrlResponse(BaseModel):
+    file_id: str
+    url: str
+    expires_at: int | None = None
+    mime_type: str
+
+
+class MultimodalConfigResponse(BaseModel):
+    media_storage_type: str
+    media_max_size_mb: float
+    document_handling: str

tenxgraph_api/src/app/routers/ping/__init__.py

@@ -0,0 +1,4 @@
+from .router import router
+
+
+__all__ = ["router"]

tenxgraph_api/src/app/routers/ping/router.py

@@ -0,0 +1,28 @@
+from fastapi import APIRouter, Request
+
+from tenxgraph_api.src.app.utils.response_helper import success_response
+from tenxgraph_api.src.app.utils.swagger_helper import generate_swagger_responses
+
+
+router = APIRouter(
+    tags=["Ping"],
+)
+
+
+@router.get(
+    "/ping",
+    summary="Ping the server",
+    responses=generate_swagger_responses(str),  # type: ignore
+    description="Check the server's health",
+    openapi_extra={},
+)
+async def ping_server(
+    request: Request,
+):
+    """
+    Invoke the graph with the provided input and return the final result.
+    """
+    return success_response(
+        "pong",
+        request,
+    )

tenxgraph_api/src/app/routers/setup_router.py

@@ -0,0 +1,60 @@
+from fastapi import APIRouter, FastAPI
+
+from .checkpointer.router import router as checkpointer_router
+from .evals import router as evals_router
+from .graph import router as graph_router
+from .media.router import router as media_router
+from .ping.router import router as ping_router
+from .store import router as store_router
+
+
+AG_UI_INSTALL_HINT = 'pip install "10xgraph-api[ag-ui]"'
+
+
+def _import_ag_ui_router() -> APIRouter:
+    from .ag_ui import router
+
+    return router
+
+
+def _ag_ui_router() -> APIRouter:
+    """Import the AG-UI router, which needs the optional ``ag-ui-protocol`` package.
+
+    Imported only when ``ag_ui.enabled`` is set, so servers that leave it off never need the
+    package installed.
+    """
+    try:
+        return _import_ag_ui_router()
+    except ModuleNotFoundError as exc:
+        if exc.name and exc.name.split(".")[0] == "ag_ui":
+            raise RuntimeError(
+                "ag_ui is enabled in 10xgraph.json but the AG-UI SDK is not installed. "
+                f"Install it with: {AG_UI_INSTALL_HINT}"
+            ) from exc
+        raise
+
+
+def init_routes(app: FastAPI, *, evals: bool = True, ag_ui: bool = False):
+    """
+    Initialize the routes for the FastAPI application.
+
+    This function includes the graph and checkpointer routers for 10xGraph functionality.
+    Auth and GraphQL routers are disabled for now.
+
+    Args:
+        app (FastAPI): The FastAPI application instance to which the routes
+        will be added.
+        evals (bool): Mount the evals report viewer. It has no auth, so production
+        leaves it out.
+        ag_ui (bool): Mount the AG-UI endpoint (``POST /v1/ag-ui``). Off unless
+        ``ag_ui.enabled`` is set in 10xgraph.json.
+    """
+    app.include_router(graph_router)
+    app.include_router(checkpointer_router)
+    app.include_router(store_router)
+    if evals:
+        app.include_router(evals_router)
+    if ag_ui:
+        app.include_router(_ag_ui_router())
+    app.include_router(ping_router)
+    app.include_router(media_router)

tenxgraph_api/src/app/routers/store/__init__.py

@@ -0,0 +1,4 @@
+from .router import router
+
+
+__all__ = ["router"]

tenxgraph_api/src/app/routers/store/router.py

@@ -0,0 +1,200 @@
+"""Store router module."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Request, status
+from injectq.integrations import InjectAPI
+
+from tenxgraph_api.src.app.core.auth.permissions import RequirePermission
+from tenxgraph_api.src.app.utils.response_helper import success_response
+from tenxgraph_api.src.app.utils.swagger_helper import generate_swagger_responses
+
+from .schemas.store_schemas import (
+    DeleteMemorySchema,
+    ForgetMemorySchema,
+    GetMemorySchema,
+    ListMemoriesSchema,
+    MemoryCreateResponseSchema,
+    MemoryItemResponseSchema,
+    MemoryListResponseSchema,
+    MemoryOperationResponseSchema,
+    MemorySearchResponseSchema,
+    SearchMemorySchema,
+    StoreMemorySchema,
+    UpdateMemorySchema,
+)
+from .services.store_service import StoreService
+
+
+router = APIRouter(tags=["store"])
+
+
+@router.post(
+    "/v1/store/memories",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryCreateResponseSchema),
+    summary="Store a memory",
+    description="Persist a memory payload using the configured store backend.",
+)
+async def create_memory(
+    request: Request,
+    payload: StoreMemorySchema,
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "write")),
+):
+    """Store a memory item using the configured store."""
+
+    result = await service.store_memory(payload, user)
+    return success_response(result, request, message="Memory stored successfully")
+
+
+@router.post(
+    "/v1/store/search",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemorySearchResponseSchema),
+    summary="Search memories",
+    description="Search memories stored in the backend based on semantic similarity and filters.",
+)
+async def search_memories(
+    request: Request,
+    payload: SearchMemorySchema,
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "read")),
+):
+    """Search stored memories."""
+    if not payload.query or (isinstance(payload.query, str) and not payload.query.strip()):
+        raise HTTPException(status_code=422, detail="query is required and cannot be empty")
+
+    result = await service.search_memories(payload, user)
+    return success_response(result, request)
+
+
+# NOTE: static sub-paths (/list, /forget) MUST be registered before the
+# /{memory_id} catch-all below — FastAPI matches top-down, so otherwise
+# `POST /v1/store/memories/list` binds to `{memory_id="list"}` and never lists.
+@router.post(
+    "/v1/store/memories/list",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryListResponseSchema),
+    summary="List memories",
+    description="List memories from the configured store backend.",
+)
+async def list_memories(
+    request: Request,
+    payload: ListMemoriesSchema | None = Body(
+        default=None,
+        description="Optional configuration, limit, and options for listing memories.",
+    ),
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "read")),
+):
+    """List stored memories."""
+
+    if payload and payload.limit is not None and payload.limit <= 0:
+        raise HTTPException(status_code=422, detail="limit must be > 0")
+
+    if payload is None:
+        payload = ListMemoriesSchema()
+    cfg = payload.config or {}
+    opts = payload.options
+    result = await service.list_memories(cfg, user, limit=payload.limit, options=opts)
+    return success_response(result, request)
+
+
+@router.put(
+    "/v1/store/memories/{memory_id}",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryOperationResponseSchema),
+    summary="Update a memory",
+    description="Update the content or metadata of a stored memory.",
+)
+async def update_memory(
+    request: Request,
+    memory_id: str,
+    payload: UpdateMemorySchema,
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "write")),
+):
+    """Update a stored memory."""
+    if not memory_id or not memory_id.strip():
+        raise HTTPException(status_code=422, detail="memory_id is required and cannot be empty")
+
+    result = await service.update_memory(memory_id, payload, user)
+    return success_response(result, request, message="Memory updated successfully")
+
+
+@router.delete(
+    "/v1/store/memories/{memory_id}",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryOperationResponseSchema),
+    summary="Delete a memory",
+    description="Delete a stored memory by its identifier.",
+)
+async def delete_memory(
+    request: Request,
+    memory_id: str,
+    payload: DeleteMemorySchema | None = Body(
+        default=None,
+        description="Optional configuration overrides forwarded to the store backend.",
+    ),
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "delete")),
+):
+    """Delete a stored memory."""
+    if not memory_id or not memory_id.strip():
+        raise HTTPException(status_code=422, detail="memory_id is required and cannot be empty")
+
+    config_payload = payload.config if payload else {}
+    options_payload = payload.options if payload else None
+    result = await service.delete_memory(memory_id, config_payload, user, options=options_payload)
+    return success_response(result, request, message="Memory deleted successfully")
+
+
+@router.post(
+    "/v1/store/memories/forget",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryOperationResponseSchema),
+    summary="Forget memories",
+    description="Forget memories matching the provided filters from the store backend.",
+)
+async def forget_memory(
+    request: Request,
+    payload: ForgetMemorySchema,
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "delete")),
+):
+    """Forget memories based on filters."""
+
+    result = await service.forget_memory(payload, user)
+    return success_response(result, request, message="Memories removed successfully")
+
+
+# Registered last so the static /list and /forget paths above take precedence
+# over this {memory_id} catch-all.
+@router.post(
+    "/v1/store/memories/{memory_id}",
+    status_code=status.HTTP_200_OK,
+    responses=generate_swagger_responses(MemoryItemResponseSchema),
+    summary="Get a memory",
+    description="Retrieve a memory by its identifier from the configured store backend.",
+)
+async def get_memory(
+    request: Request,
+    memory_id: str,
+    payload: GetMemorySchema | None = Body(
+        default=None,
+        description="Optional configuration and options for retrieving the memory.",
+    ),
+    service: StoreService = InjectAPI(StoreService),
+    user: dict[str, Any] = Depends(RequirePermission("store", "read")),
+):
+    """Get a memory by ID."""
+    if not memory_id or not memory_id.strip():
+        raise HTTPException(status_code=422, detail="memory_id is required and cannot be empty")
+
+    cfg = payload.config if payload else {}
+    opts = payload.options if payload else None
+    result = await service.get_memory(memory_id, cfg, user, options=opts)
+    return success_response(result, request)

tenxgraph_api/src/app/routers/store/schemas/__init__.py

@@ -0,0 +1,28 @@
+from .store_schemas import (
+    BaseConfigSchema,
+    DeleteMemorySchema,
+    ForgetMemorySchema,
+    MemoryCreateResponseSchema,
+    MemoryItemResponseSchema,
+    MemoryListResponseSchema,
+    MemoryOperationResponseSchema,
+    MemorySearchResponseSchema,
+    SearchMemorySchema,
+    StoreMemorySchema,
+    UpdateMemorySchema,
+)
+
+
+__all__ = [
+    "BaseConfigSchema",
+    "DeleteMemorySchema",
+    "ForgetMemorySchema",
+    "MemoryCreateResponseSchema",
+    "MemoryItemResponseSchema",
+    "MemoryListResponseSchema",
+    "MemoryOperationResponseSchema",
+    "MemorySearchResponseSchema",
+    "SearchMemorySchema",
+    "StoreMemorySchema",
+    "UpdateMemorySchema",
+]