neural-memory 0.1.0__py3-none-any.whl

neural_memory/server/models.py

@@ -0,0 +1,138 @@
+"""Pydantic models for API request/response."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# ============ Request Models ============
+
+
+class EncodeRequest(BaseModel):
+    """Request to encode a new memory."""
+
+    content: str = Field(..., description="The content to encode as a memory")
+    timestamp: datetime | None = Field(None, description="When this memory occurred (default: now)")
+    metadata: dict[str, Any] | None = Field(None, description="Additional metadata to attach")
+    tags: list[str] | None = Field(None, description="Tags for categorization")
+
+
+class QueryRequest(BaseModel):
+    """Request to query memories."""
+
+    query: str = Field(..., description="The query text")
+    depth: int | None = Field(
+        None,
+        ge=0,
+        le=3,
+        description="Retrieval depth (0=instant, 1=context, 2=habit, 3=deep). Auto-detects if not specified.",
+    )
+    max_tokens: int = Field(
+        500,
+        ge=50,
+        le=5000,
+        description="Maximum tokens in returned context",
+    )
+    include_subgraph: bool = Field(False, description="Whether to include subgraph details")
+    reference_time: datetime | None = Field(
+        None, description="Reference time for temporal parsing (default: now)"
+    )
+
+
+class CreateBrainRequest(BaseModel):
+    """Request to create a new brain."""
+
+    name: str = Field(..., min_length=1, max_length=100, description="Brain name")
+    owner_id: str | None = Field(None, description="Owner identifier")
+    is_public: bool = Field(False, description="Whether publicly accessible")
+    config: BrainConfigModel | None = Field(None, description="Custom configuration")
+
+
+class BrainConfigModel(BaseModel):
+    """Brain configuration model."""
+
+    decay_rate: float = Field(0.1, ge=0, le=1)
+    reinforcement_delta: float = Field(0.05, ge=0, le=0.5)
+    activation_threshold: float = Field(0.2, ge=0, le=1)
+    max_spread_hops: int = Field(4, ge=1, le=10)
+    max_context_tokens: int = Field(1500, ge=100, le=10000)
+
+
+# ============ Response Models ============
+
+
+class EncodeResponse(BaseModel):
+    """Response from encoding a memory."""
+
+    fiber_id: str = Field(..., description="ID of the created fiber")
+    neurons_created: int = Field(..., description="Number of neurons created")
+    neurons_linked: int = Field(..., description="Number of existing neurons linked")
+    synapses_created: int = Field(..., description="Number of synapses created")
+
+
+class SubgraphResponse(BaseModel):
+    """Subgraph details in query response."""
+
+    neuron_ids: list[str]
+    synapse_ids: list[str]
+    anchor_ids: list[str]
+
+
+class QueryResponse(BaseModel):
+    """Response from querying memories."""
+
+    answer: str | None = Field(None, description="Reconstructed answer if available")
+    confidence: float = Field(..., ge=0, le=1, description="Confidence in answer")
+    depth_used: int = Field(..., description="Depth level used for retrieval")
+    neurons_activated: int = Field(..., description="Number of neurons activated")
+    fibers_matched: list[str] = Field(..., description="IDs of matched fibers")
+    context: str = Field(..., description="Formatted context for injection")
+    latency_ms: float = Field(..., description="Retrieval latency in milliseconds")
+    subgraph: SubgraphResponse | None = Field(None, description="Subgraph details (if requested)")
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class BrainResponse(BaseModel):
+    """Response with brain details."""
+
+    id: str
+    name: str
+    owner_id: str | None
+    is_public: bool
+    neuron_count: int
+    synapse_count: int
+    fiber_count: int
+    created_at: datetime
+    updated_at: datetime
+
+
+class BrainListResponse(BaseModel):
+    """Response with list of brains."""
+
+    brains: list[BrainResponse]
+    total: int
+
+
+class StatsResponse(BaseModel):
+    """Response with brain statistics."""
+
+    brain_id: str
+    neuron_count: int
+    synapse_count: int
+    fiber_count: int
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str = "healthy"
+    version: str
+
+
+class ErrorResponse(BaseModel):
+    """Error response."""
+
+    error: str
+    detail: str | None = None

neural_memory/server/routes/__init__.py

@@ -0,0 +1,7 @@
+"""API routes for NeuralMemory server."""
+
+from neural_memory.server.routes.brain import router as brain_router
+from neural_memory.server.routes.memory import router as memory_router
+from neural_memory.server.routes.sync import router as sync_router
+
+__all__ = ["brain_router", "memory_router", "sync_router"]

neural_memory/server/routes/brain.py

@@ -0,0 +1,221 @@
+"""Brain API routes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from neural_memory.core.brain import Brain, BrainConfig
+from neural_memory.server.dependencies import get_storage
+from neural_memory.server.models import (
+    BrainResponse,
+    CreateBrainRequest,
+    ErrorResponse,
+    StatsResponse,
+)
+from neural_memory.storage.base import NeuralStorage
+
+router = APIRouter(prefix="/brain", tags=["brain"])
+
+
+@router.post(
+    "/create",
+    response_model=BrainResponse,
+    summary="Create a new brain",
+    description="Create a new brain for storing memories.",
+)
+async def create_brain(
+    request: CreateBrainRequest,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> BrainResponse:
+    """Create a new brain."""
+    # Build config
+    config = BrainConfig()
+    if request.config:
+        config = BrainConfig(
+            decay_rate=request.config.decay_rate,
+            reinforcement_delta=request.config.reinforcement_delta,
+            activation_threshold=request.config.activation_threshold,
+            max_spread_hops=request.config.max_spread_hops,
+            max_context_tokens=request.config.max_context_tokens,
+        )
+
+    brain = Brain.create(
+        name=request.name,
+        config=config,
+        owner_id=request.owner_id,
+        is_public=request.is_public,
+    )
+
+    await storage.save_brain(brain)
+
+    return BrainResponse(
+        id=brain.id,
+        name=brain.name,
+        owner_id=brain.owner_id,
+        is_public=brain.is_public,
+        neuron_count=0,
+        synapse_count=0,
+        fiber_count=0,
+        created_at=brain.created_at,
+        updated_at=brain.updated_at,
+    )
+
+
+@router.get(
+    "/{brain_id}",
+    response_model=BrainResponse,
+    responses={404: {"model": ErrorResponse}},
+    summary="Get brain details",
+    description="Get details of a specific brain.",
+)
+async def get_brain(
+    brain_id: str,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> BrainResponse:
+    """Get brain by ID."""
+    brain = await storage.get_brain(brain_id)
+    if brain is None:
+        raise HTTPException(status_code=404, detail=f"Brain {brain_id} not found")
+
+    # Get current stats
+    stats = await storage.get_stats(brain_id)
+
+    return BrainResponse(
+        id=brain.id,
+        name=brain.name,
+        owner_id=brain.owner_id,
+        is_public=brain.is_public,
+        neuron_count=stats["neuron_count"],
+        synapse_count=stats["synapse_count"],
+        fiber_count=stats["fiber_count"],
+        created_at=brain.created_at,
+        updated_at=brain.updated_at,
+    )
+
+
+@router.get(
+    "/{brain_id}/stats",
+    response_model=StatsResponse,
+    responses={404: {"model": ErrorResponse}},
+    summary="Get brain statistics",
+    description="Get statistics for a brain.",
+)
+async def get_brain_stats(
+    brain_id: str,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> StatsResponse:
+    """Get brain statistics."""
+    brain = await storage.get_brain(brain_id)
+    if brain is None:
+        raise HTTPException(status_code=404, detail=f"Brain {brain_id} not found")
+
+    stats = await storage.get_stats(brain_id)
+
+    return StatsResponse(
+        brain_id=brain_id,
+        neuron_count=stats["neuron_count"],
+        synapse_count=stats["synapse_count"],
+        fiber_count=stats["fiber_count"],
+    )
+
+
+@router.get(
+    "/{brain_id}/export",
+    responses={404: {"model": ErrorResponse}},
+    summary="Export brain",
+    description="Export a brain as a JSON snapshot.",
+)
+async def export_brain(
+    brain_id: str,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> dict:
+    """Export brain as snapshot."""
+    brain = await storage.get_brain(brain_id)
+    if brain is None:
+        raise HTTPException(status_code=404, detail=f"Brain {brain_id} not found")
+
+    snapshot = await storage.export_brain(brain_id)
+
+    return {
+        "brain_id": snapshot.brain_id,
+        "brain_name": snapshot.brain_name,
+        "exported_at": snapshot.exported_at.isoformat(),
+        "version": snapshot.version,
+        "neurons": snapshot.neurons,
+        "synapses": snapshot.synapses,
+        "fibers": snapshot.fibers,
+        "config": snapshot.config,
+        "metadata": snapshot.metadata,
+    }
+
+
+@router.post(
+    "/{brain_id}/import",
+    response_model=BrainResponse,
+    summary="Import brain",
+    description="Import a brain from a JSON snapshot.",
+)
+async def import_brain(
+    brain_id: str,
+    snapshot: dict,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> BrainResponse:
+    """Import brain from snapshot."""
+    from datetime import datetime
+
+    from neural_memory.core.brain import BrainSnapshot
+
+    # Convert dict to BrainSnapshot
+    brain_snapshot = BrainSnapshot(
+        brain_id=snapshot.get("brain_id", brain_id),
+        brain_name=snapshot["brain_name"],
+        exported_at=datetime.fromisoformat(snapshot["exported_at"]),
+        version=snapshot["version"],
+        neurons=snapshot["neurons"],
+        synapses=snapshot["synapses"],
+        fibers=snapshot["fibers"],
+        config=snapshot["config"],
+        metadata=snapshot.get("metadata", {}),
+    )
+
+    imported_id = await storage.import_brain(brain_snapshot, brain_id)
+
+    brain = await storage.get_brain(imported_id)
+    if brain is None:
+        raise HTTPException(status_code=500, detail="Import failed")
+
+    stats = await storage.get_stats(imported_id)
+
+    return BrainResponse(
+        id=brain.id,
+        name=brain.name,
+        owner_id=brain.owner_id,
+        is_public=brain.is_public,
+        neuron_count=stats["neuron_count"],
+        synapse_count=stats["synapse_count"],
+        fiber_count=stats["fiber_count"],
+        created_at=brain.created_at,
+        updated_at=brain.updated_at,
+    )
+
+
+@router.delete(
+    "/{brain_id}",
+    responses={404: {"model": ErrorResponse}},
+    summary="Delete brain",
+    description="Delete a brain and all its data.",
+)
+async def delete_brain(
+    brain_id: str,
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> dict:
+    """Delete a brain."""
+    brain = await storage.get_brain(brain_id)
+    if brain is None:
+        raise HTTPException(status_code=404, detail=f"Brain {brain_id} not found")
+
+    await storage.clear(brain_id)
+
+    return {"status": "deleted", "brain_id": brain_id}

neural_memory/server/routes/memory.py

@@ -0,0 +1,169 @@
+"""Memory API routes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from neural_memory.core.brain import Brain
+from neural_memory.engine.encoder import MemoryEncoder
+from neural_memory.engine.retrieval import DepthLevel, ReflexPipeline
+from neural_memory.server.dependencies import get_brain, get_storage
+from neural_memory.server.models import (
+    EncodeRequest,
+    EncodeResponse,
+    ErrorResponse,
+    QueryRequest,
+    QueryResponse,
+    SubgraphResponse,
+)
+from neural_memory.storage.base import NeuralStorage
+
+router = APIRouter(prefix="/memory", tags=["memory"])
+
+
+@router.post(
+    "/encode",
+    response_model=EncodeResponse,
+    responses={404: {"model": ErrorResponse}},
+    summary="Encode a new memory",
+    description="Store a new memory by encoding content into neural structures.",
+)
+async def encode_memory(
+    request: EncodeRequest,
+    brain: Annotated[Brain, Depends(get_brain)],
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> EncodeResponse:
+    """Encode new content as a memory."""
+    encoder = MemoryEncoder(storage, brain.config)
+
+    tags = set(request.tags) if request.tags else None
+
+    result = await encoder.encode(
+        content=request.content,
+        timestamp=request.timestamp,
+        metadata=request.metadata,
+        tags=tags,
+    )
+
+    return EncodeResponse(
+        fiber_id=result.fiber.id,
+        neurons_created=len(result.neurons_created),
+        neurons_linked=len(result.neurons_linked),
+        synapses_created=len(result.synapses_created),
+    )
+
+
+@router.post(
+    "/query",
+    response_model=QueryResponse,
+    responses={404: {"model": ErrorResponse}},
+    summary="Query memories",
+    description="Query memories through spreading activation retrieval.",
+)
+async def query_memory(
+    request: QueryRequest,
+    brain: Annotated[Brain, Depends(get_brain)],
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> QueryResponse:
+    """Query memories using the reflex pipeline."""
+    pipeline = ReflexPipeline(storage, brain.config)
+
+    depth = DepthLevel(request.depth) if request.depth is not None else None
+
+    result = await pipeline.query(
+        query=request.query,
+        depth=depth,
+        max_tokens=request.max_tokens,
+        reference_time=request.reference_time,
+    )
+
+    subgraph = None
+    if request.include_subgraph:
+        subgraph = SubgraphResponse(
+            neuron_ids=result.subgraph.neuron_ids,
+            synapse_ids=result.subgraph.synapse_ids,
+            anchor_ids=result.subgraph.anchor_ids,
+        )
+
+    return QueryResponse(
+        answer=result.answer,
+        confidence=result.confidence,
+        depth_used=result.depth_used.value,
+        neurons_activated=result.neurons_activated,
+        fibers_matched=result.fibers_matched,
+        context=result.context,
+        latency_ms=result.latency_ms,
+        subgraph=subgraph,
+        metadata=result.metadata,
+    )
+
+
+@router.get(
+    "/fiber/{fiber_id}",
+    responses={404: {"model": ErrorResponse}},
+    summary="Get a specific fiber",
+    description="Retrieve details of a specific memory fiber.",
+)
+async def get_fiber(
+    fiber_id: str,
+    brain: Annotated[Brain, Depends(get_brain)],
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> dict:
+    """Get a specific fiber by ID."""
+    fiber = await storage.get_fiber(fiber_id)
+    if fiber is None:
+        raise HTTPException(status_code=404, detail=f"Fiber {fiber_id} not found")
+
+    return {
+        "id": fiber.id,
+        "neuron_ids": list(fiber.neuron_ids),
+        "synapse_ids": list(fiber.synapse_ids),
+        "anchor_neuron_id": fiber.anchor_neuron_id,
+        "time_start": fiber.time_start.isoformat() if fiber.time_start else None,
+        "time_end": fiber.time_end.isoformat() if fiber.time_end else None,
+        "coherence": fiber.coherence,
+        "salience": fiber.salience,
+        "frequency": fiber.frequency,
+        "summary": fiber.summary,
+        "tags": list(fiber.tags),
+        "created_at": fiber.created_at.isoformat(),
+    }
+
+
+@router.get(
+    "/neurons",
+    summary="List neurons",
+    description="List neurons in the brain with optional filters.",
+)
+async def list_neurons(
+    brain: Annotated[Brain, Depends(get_brain)],
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+    type: str | None = None,
+    content_contains: str | None = None,
+    limit: int = 50,
+) -> dict:
+    """List neurons with optional filters."""
+    from neural_memory.core.neuron import NeuronType
+
+    neuron_type = NeuronType(type) if type else None
+
+    neurons = await storage.find_neurons(
+        type=neuron_type,
+        content_contains=content_contains,
+        limit=limit,
+    )
+
+    return {
+        "neurons": [
+            {
+                "id": n.id,
+                "type": n.type.value,
+                "content": n.content,
+                "created_at": n.created_at.isoformat(),
+            }
+            for n in neurons
+        ],
+        "count": len(neurons),
+    }