hindsight-api 0.1.16__py3-none-any.whl → 0.2.0__py3-none-any.whl

hindsight_api/api/__init__.py

@@ -5,6 +5,7 @@ Provides both HTTP REST API and MCP (Model Context Protocol) server.
 """
 
 import logging
+from contextlib import asynccontextmanager
 from typing import Optional
 
 from fastapi import FastAPI
@@ -45,6 +46,18 @@ def create_app(
         # Both HTTP and MCP
         app = create_app(memory, mcp_api_enabled=True)
     """
+    mcp_app = None
+
+    # Create MCP app first if enabled (we need its lifespan for chaining)
+    if mcp_api_enabled:
+        try:
+            from .mcp import create_mcp_app
+
+            mcp_app = create_mcp_app(memory=memory)
+        except ImportError as e:
+            logger.error(f"MCP server requested but dependencies not available: {e}")
+            logger.error("Install with: pip install hindsight-api[mcp]")
+            raise
 
     # Import and create HTTP API if enabled
     if http_api_enabled:
@@ -57,20 +70,31 @@ def create_app(
         app = FastAPI(title="Hindsight API", version="0.0.7")
         logger.info("HTTP REST API disabled")
 
-    # Mount MCP server if enabled
-    if mcp_api_enabled:
-        try:
-            from .mcp import create_mcp_app
-
-            # Create MCP app with dynamic bank_id support
-            # Supports: /mcp/{bank_id}/sse (bank-specific SSE endpoint)
-            mcp_app = create_mcp_app(memory=memory)
-            app.mount(mcp_mount_path, mcp_app)
-            logger.info(f"MCP server enabled at {mcp_mount_path}/{{bank_id}}/sse")
-        except ImportError as e:
-            logger.error(f"MCP server requested but dependencies not available: {e}")
-            logger.error("Install with: pip install hindsight-api[mcp]")
-            raise
+    # Mount MCP server and chain its lifespan if enabled
+    if mcp_app is not None:
+        # Get the MCP app's underlying Starlette app for lifespan access
+        mcp_starlette_app = mcp_app.mcp_app
+
+        # Store the original lifespan
+        original_lifespan = app.router.lifespan_context
+
+        @asynccontextmanager
+        async def chained_lifespan(app_instance: FastAPI):
+            """Chain the MCP lifespan with the main app lifespan."""
+            # Start MCP lifespan first
+            async with mcp_starlette_app.router.lifespan_context(mcp_starlette_app):
+                logger.info("MCP lifespan started")
+                # Then start the original app lifespan
+                async with original_lifespan(app_instance):
+                    yield
+            logger.info("MCP lifespan stopped")
+
+        # Replace the app's lifespan with the chained version
+        app.router.lifespan_context = chained_lifespan
+
+        # Mount the MCP middleware
+        app.mount(mcp_mount_path, mcp_app)
+        logger.info(f"MCP server enabled at {mcp_mount_path}/")
 
     return app
 

hindsight_api/api/http.py

@@ -14,6 +14,8 @@ from typing import Any
 
 from fastapi import Depends, FastAPI, Header, HTTPException, Query
 
+from hindsight_api.extensions import AuthenticationError
+
 
 def _parse_metadata(metadata: Any) -> dict[str, Any]:
     """Parse metadata that may be a dict, JSON string, or None."""
@@ -35,7 +37,7 @@ from hindsight_api import MemoryEngine
 from hindsight_api.engine.db_utils import acquire_with_retry
 from hindsight_api.engine.memory_engine import Budget, fq_table
 from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
-from hindsight_api.extensions import HttpExtension, load_extension
+from hindsight_api.extensions import HttpExtension, OperationValidationError, load_extension
 from hindsight_api.metrics import create_metrics_collector, get_metrics_collector, initialize_metrics
 from hindsight_api.models import RequestContext
 
@@ -279,6 +281,13 @@ class RecallResponse(BaseModel):
     chunks: dict[str, ChunkData] | None = Field(default=None, description="Chunks for facts, keyed by chunk_id")
 
 
+class EntityInput(BaseModel):
+    """Entity to associate with retained content."""
+
+    text: str = Field(description="The entity name/text")
+    type: str | None = Field(default=None, description="Optional entity type (e.g., 'PERSON', 'ORG', 'CONCEPT')")
+
+
 class MemoryItem(BaseModel):
     """Single memory item for retain."""
 
@@ -290,6 +299,7 @@ class MemoryItem(BaseModel):
                 "context": "team meeting",
                 "metadata": {"source": "slack", "channel": "engineering"},
                 "document_id": "meeting_notes_2024_01_15",
+                "entities": [{"text": "Alice"}, {"text": "ML model", "type": "CONCEPT"}],
             }
         },
     )
@@ -299,6 +309,10 @@ class MemoryItem(BaseModel):
     context: str | None = None
     metadata: dict[str, str] | None = None
     document_id: str | None = Field(default=None, description="Optional document ID for this memory item.")
+    entities: list[EntityInput] | None = Field(
+        default=None,
+        description="Optional entities to combine with auto-extracted entities.",
+    )
 
     @field_validator("timestamp", mode="before")
     @classmethod
@@ -385,7 +399,16 @@ class ReflectRequest(BaseModel):
                 "query": "What do you think about artificial intelligence?",
                 "budget": "low",
                 "context": "This is for a research paper on AI ethics",
+                "max_tokens": 4096,
                 "include": {"facts": {}},
+                "response_schema": {
+                    "type": "object",
+                    "properties": {
+                        "summary": {"type": "string"},
+                        "key_points": {"type": "array", "items": {"type": "string"}},
+                    },
+                    "required": ["summary", "key_points"],
+                },
             }
         }
     )
@@ -393,9 +416,14 @@ class ReflectRequest(BaseModel):
     query: str
     budget: Budget = Budget.LOW
     context: str | None = None
+    max_tokens: int = Field(default=4096, description="Maximum tokens for the response")
     include: ReflectIncludeOptions = Field(
         default_factory=ReflectIncludeOptions, description="Options for including additional data (disabled by default)"
     )
+    response_schema: dict | None = Field(
+        default=None,
+        description="Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema.",
+    )
 
 
 class OpinionItem(BaseModel):
@@ -440,12 +468,20 @@ class ReflectResponse(BaseModel):
                     {"id": "123", "text": "AI is used in healthcare", "type": "world"},
                     {"id": "456", "text": "I discussed AI applications last week", "type": "experience"},
                 ],
+                "structured_output": {
+                    "summary": "AI is transformative",
+                    "key_points": ["Used in healthcare", "Discussed recently"],
+                },
             }
         }
     )
 
     text: str
     based_on: list[ReflectFact] = []  # Facts used to generate the response
+    structured_output: dict | None = Field(
+        default=None,
+        description="Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.",
+    )
 
 
 class BanksResponse(BaseModel):
@@ -967,6 +1003,16 @@ def _register_routes(app: FastAPI):
                 api_key = authorization.strip()
         return RequestContext(api_key=api_key)
 
+    # Global exception handler for authentication errors
+    @app.exception_handler(AuthenticationError)
+    async def authentication_error_handler(request, exc: AuthenticationError):
+        from fastapi.responses import JSONResponse
+
+        return JSONResponse(
+            status_code=401,
+            content={"detail": str(exc)},
+        )
+
     @app.get(
         "/health",
         summary="Health check endpoint",
@@ -1014,6 +1060,8 @@ def _register_routes(app: FastAPI):
         try:
             data = await app.state.memory.get_graph_data(bank_id, type, request_context=request_context)
             return data
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1060,6 +1108,8 @@ def _register_routes(app: FastAPI):
                 request_context=request_context,
             )
             return data
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1176,6 +1226,10 @@ def _register_routes(app: FastAPI):
             )
         except HTTPException:
             raise
+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1211,6 +1265,8 @@ def _register_routes(app: FastAPI):
                     query=request.query,
                     budget=request.budget,
                     context=request.context,
+                    max_tokens=request.max_tokens,
+                    response_schema=request.response_schema,
                     request_context=request_context,
                 )
 
@@ -1233,8 +1289,13 @@ def _register_routes(app: FastAPI):
             return ReflectResponse(
                 text=core_result.text,
                 based_on=based_on_facts,
+                structured_output=core_result.structured_output,
             )
 
+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1255,6 +1316,8 @@ def _register_routes(app: FastAPI):
         try:
             banks = await app.state.memory.list_banks(request_context=request_context)
             return BankListResponse(banks=banks)
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1378,6 +1441,8 @@ def _register_routes(app: FastAPI):
                     failed_operations=failed_operations,
                 )
 
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1402,6 +1467,8 @@ def _register_routes(app: FastAPI):
         try:
             entities = await app.state.memory.list_entities(bank_id, limit=limit, request_context=request_context)
             return EntityListResponse(items=[EntityListItem(**e) for e in entities])
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1439,7 +1506,7 @@ def _register_routes(app: FastAPI):
                     for obs in entity["observations"]
                 ],
             )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
@@ -1492,7 +1559,7 @@ def _register_routes(app: FastAPI):
                     for obs in entity["observations"]
                 ],
             )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
@@ -1530,6 +1597,8 @@ def _register_routes(app: FastAPI):
                 bank_id=bank_id, search_query=q, limit=limit, offset=offset, request_context=request_context
             )
             return data
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1538,7 +1607,7 @@ def _register_routes(app: FastAPI):
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.get(
-        "/v1/default/banks/{bank_id}/documents/{document_id}",
+        "/v1/default/banks/{bank_id}/documents/{document_id:path}",
         response_model=DocumentResponse,
         summary="Get document details",
         description="Get a specific document including its original text",
@@ -1560,7 +1629,7 @@ def _register_routes(app: FastAPI):
             if not document:
                 raise HTTPException(status_code=404, detail="Document not found")
             return document
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
@@ -1570,7 +1639,7 @@ def _register_routes(app: FastAPI):
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.get(
-        "/v1/default/chunks/{chunk_id}",
+        "/v1/default/chunks/{chunk_id:path}",
         response_model=ChunkResponse,
         summary="Get chunk details",
         description="Get a specific chunk by its ID",
@@ -1589,7 +1658,7 @@ def _register_routes(app: FastAPI):
             if not chunk:
                 raise HTTPException(status_code=404, detail="Chunk not found")
             return chunk
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
@@ -1599,7 +1668,7 @@ def _register_routes(app: FastAPI):
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.delete(
-        "/v1/default/banks/{bank_id}/documents/{document_id}",
+        "/v1/default/banks/{bank_id}/documents/{document_id:path}",
         response_model=DeleteDocumentResponse,
         summary="Delete a document",
         description="Delete a document and all its associated memory units and links.\n\n"
@@ -1633,7 +1702,7 @@ def _register_routes(app: FastAPI):
                 document_id=document_id,
                 memory_units_deleted=result["memory_units_deleted"],
             )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
@@ -1658,6 +1727,8 @@ def _register_routes(app: FastAPI):
                 bank_id=bank_id,
                 operations=[OperationResponse(**op) for op in operations],
             )
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1688,6 +1759,8 @@ def _register_routes(app: FastAPI):
             return CancelOperationResponse(**result)
         except ValueError as e:
             raise HTTPException(status_code=404, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1719,6 +1792,8 @@ def _register_routes(app: FastAPI):
                 disposition=DispositionTraits(**disposition_dict),
                 background=profile["background"],
             )
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1757,6 +1832,8 @@ def _register_routes(app: FastAPI):
                 disposition=DispositionTraits(**disposition_dict),
                 background=profile["background"],
             )
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1786,6 +1863,8 @@ def _register_routes(app: FastAPI):
                 response.disposition = DispositionTraits(**result["disposition"])
 
             return response
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1837,6 +1916,8 @@ def _register_routes(app: FastAPI):
                 disposition=DispositionTraits(**disposition_dict),
                 background=final_profile["background"],
             )
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1864,6 +1945,8 @@ def _register_routes(app: FastAPI):
                 + result.get("entities_deleted", 0)
                 + result.get("documents_deleted", 0),
             )
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1915,6 +1998,8 @@ def _register_routes(app: FastAPI):
                     content_dict["metadata"] = item.metadata
                 if item.document_id:
                     content_dict["document_id"] = item.document_id
+                if item.entities:
+                    content_dict["entities"] = [{"text": e.text, "type": e.type or "CONCEPT"} for e in item.entities]
                 contents.append(content_dict)
 
             if request.async_:
@@ -1938,6 +2023,10 @@ def _register_routes(app: FastAPI):
                 return RetainResponse.model_validate(
                     {"success": True, "bank_id": bank_id, "items_count": len(contents), "async": False}
                 )
+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback
 
@@ -1976,6 +2065,8 @@ def _register_routes(app: FastAPI):
             await app.state.memory.delete_bank(bank_id, fact_type=type, request_context=request_context)
 
             return DeleteResponse(success=True)
+        except (AuthenticationError, HTTPException):
+            raise
         except Exception as e:
             import traceback