Upload 79 files

Dockerfile

@@ -1,33 +1,24 @@
-# ==============================================================================
-# Dockerfile — AetherMap API (versão profissional)
-# ==============================================================================
+FROM python:3.11-slim
 
-# Imagem Python robusta (não slim → evita erros de build)
-FROM python:3.10
-
-# Define diretório da aplicação
 WORKDIR /app
 
-# --- INSTALAR TORCH CPU ANTES (CRÍTICO!) ---
-# Isso garante que a versão certa (CPU) seja instalada
-RUN pip install --no-cache-dir \
-    torch \
-    torchvision \
-    torchaudio \
-    --index-url https://download.pytorch.org/whl/cpu
-
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
 
-# Copiar requirements
+# Copy requirements first for better caching
 COPY requirements.txt .
-
-# Instalar dependências restantes
 RUN pip install --no-cache-dir -r requirements.txt
 
-# Copiar código da aplicação
+# Copy application code
 COPY . .
 
-# Expor porta usada pelo Hugging Face Spaces
+# Create data directory for SQLite
+RUN mkdir -p /app/data
+
+# Expose port (HF Spaces uses 7860)
 EXPOSE 7860
 
-# Comando padrão para executar FastAPI
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,27 @@
 ---
-title: AetherMap
-emoji: 🦀
-colorFrom: indigo
-colorTo: pink
+title: Numidium
+emoji: 🔮
+colorFrom: blue
+colorTo: red
 sdk: docker
 pinned: false
-license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Numidium API
+
+Backend do sistema de inteligência Numidium/VANTAGE.
+
+## Endpoints
+
+- `/docs` - Documentação Swagger
+- `/api/v1/entities` - CRUD de entidades
+- `/api/v1/relationships` - Conexões
+- `/api/v1/events` - Eventos
+- `/api/v1/search` - Busca global
+- `/api/v1/ingest` - Ingestão de dados (Wikipedia, News)
+
+## Stack
+
+- FastAPI
+- SQLite
+- BeautifulSoup (scraping)

app/__init__.py

@@ -0,0 +1 @@
+# Numidium Backend App

app/api/__init__.py

@@ -0,0 +1 @@
+# API module

app/api/deps.py

@@ -0,0 +1,35 @@
+"""
+API dependencies.
+"""
+from typing import Generator, Optional
+
+from fastapi import Cookie, Header
+from sqlalchemy.orm import Session
+
+from app.core.database import get_db_for_session, get_default_session
+
+
+def get_session_id(
+    x_session_id: Optional[str] = Header(None),
+    numidium_session: Optional[str] = Cookie(None)
+) -> Optional[str]:
+    """Return the session id from header or cookie."""
+    return x_session_id or numidium_session
+
+
+def get_scoped_db(
+    x_session_id: Optional[str] = Header(None),
+    numidium_session: Optional[str] = Cookie(None)
+) -> Generator[Session, None, None]:
+    """
+    Provide a session-scoped DB if available, otherwise the default DB.
+    """
+    session_id = x_session_id or numidium_session
+    if session_id:
+        db = get_db_for_session(session_id)
+    else:
+        db = get_default_session()
+    try:
+        yield db
+    finally:
+        db.close()

app/api/routes/__init__.py

@@ -0,0 +1,2 @@
+# API Routes module
+from app.api.routes import entities, relationships, events, search, ingest

app/api/routes/aethermap.py

@@ -0,0 +1,307 @@
+"""
+AetherMap Routes - Document Mapping & Semantic Search
+Integrates with AetherMap API for document clustering, NER, and semantic search.
+"""
+from fastapi import APIRouter, HTTPException, UploadFile, File, Form, Depends
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+from sqlalchemy.orm import Session
+import io
+
+from app.api.deps import get_scoped_db
+from app.services.aethermap_client import aethermap, ProcessResult, SearchResult, EntityGraphResult
+
+
+router = APIRouter()
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+class IndexDocumentsRequest(BaseModel):
+    """Request to index documents from text list"""
+    documents: List[str] = Field(..., description="Lista de textos para indexar")
+    fast_mode: bool = Field(True, description="Modo rápido (PCA) ou preciso (UMAP)")
+
+
+class IndexEntitiesRequest(BaseModel):
+    """Request to index entities from NUMIDIUM database"""
+    entity_types: Optional[List[str]] = Field(None, description="Filtrar por tipos de entidade")
+    limit: int = Field(500, description="Limite de entidades")
+
+
+class SemanticSearchRequest(BaseModel):
+    """Request for semantic search"""
+    query: str = Field(..., description="Termo de busca")
+    turbo_mode: bool = Field(True, description="Modo turbo (mais rápido)")
+
+
+class IndexResponse(BaseModel):
+    """Response from indexing"""
+    job_id: str
+    num_documents: int
+    num_clusters: int
+    num_noise: int
+    metrics: Dict[str, Any] = {}
+    cluster_analysis: Dict[str, Any] = {}
+
+
+class SearchResponse(BaseModel):
+    """Response from search"""
+    summary: str
+    results: List[Dict[str, Any]] = []
+
+
+class EntityGraphResponse(BaseModel):
+    """Response from NER extraction"""
+    hubs: List[Dict[str, Any]] = []
+    insights: Dict[str, Any] = {}
+    node_count: int = 0
+    edge_count: int = 0
+
+
+class StatusResponse(BaseModel):
+    """AetherMap status"""
+    connected: bool
+    job_id: Optional[str] = None
+    documents_indexed: int = 0
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+@router.get("/status", response_model=StatusResponse)
+async def get_status():
+    """
+    Get AetherMap connection status.
+    """
+    return StatusResponse(
+        connected=True,
+        job_id=aethermap.current_job_id,
+        documents_indexed=0  # TODO: track this
+    )
+
+
+@router.post("/index", response_model=IndexResponse)
+async def index_documents(request: IndexDocumentsRequest):
+    """
+    Index a list of documents for semantic search.
+    
+    The documents will be:
+    - Embedded using sentence transformers
+    - Clustered using HDBSCAN
+    - Indexed in FAISS + BM25 for hybrid search
+    """
+    try:
+        if not request.documents:
+            raise HTTPException(status_code=400, detail="Nenhum documento fornecido")
+        
+        result = await aethermap.process_documents(
+            texts=request.documents,
+            fast_mode=request.fast_mode
+        )
+        
+        return IndexResponse(
+            job_id=result.job_id,
+            num_documents=result.num_documents,
+            num_clusters=result.num_clusters,
+            num_noise=result.num_noise,
+            metrics=result.metrics,
+            cluster_analysis=result.cluster_analysis
+        )
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/index-entities", response_model=IndexResponse)
+async def index_entities(
+    request: IndexEntitiesRequest,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Index entities from NUMIDIUM database.
+    
+    Collects entity names and descriptions, sends to AetherMap for processing.
+    """
+    from app.models.entity import Entity
+    
+    try:
+        query = db.query(Entity)
+        
+        if request.entity_types:
+            query = query.filter(Entity.type.in_(request.entity_types))
+        
+        entities = query.limit(request.limit).all()
+        
+        if not entities:
+            raise HTTPException(status_code=404, detail="Nenhuma entidade encontrada")
+        
+        # Build text representations
+        documents = []
+        for e in entities:
+            text = f"{e.name} ({e.type})"
+            if e.description:
+                text += f": {e.description[:1000]}"
+            documents.append(text)
+        
+        result = await aethermap.process_documents(
+            texts=documents,
+            fast_mode=request.fast_mode if hasattr(request, 'fast_mode') else True
+        )
+        
+        return IndexResponse(
+            job_id=result.job_id,
+            num_documents=result.num_documents,
+            num_clusters=result.num_clusters,
+            num_noise=result.num_noise,
+            metrics=result.metrics,
+            cluster_analysis=result.cluster_analysis
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/upload", response_model=IndexResponse)
+async def upload_documents(
+    file: UploadFile = File(...),
+    fast_mode: bool = Form(True)
+):
+    """
+    Upload a file (TXT or CSV) for indexing.
+    
+    - TXT: One document per line
+    - CSV: Will use first text column found
+    """
+    try:
+        content = await file.read()
+        text = content.decode('utf-8', errors='ignore')
+        
+        # Split by lines for TXT
+        documents = [line.strip() for line in text.splitlines() if line.strip()]
+        
+        if not documents:
+            raise HTTPException(status_code=400, detail="Arquivo vazio ou sem texto válido")
+        
+        result = await aethermap.process_documents(
+            texts=documents,
+            fast_mode=fast_mode
+        )
+        
+        return IndexResponse(
+            job_id=result.job_id,
+            num_documents=result.num_documents,
+            num_clusters=result.num_clusters,
+            num_noise=result.num_noise,
+            metrics=result.metrics,
+            cluster_analysis=result.cluster_analysis
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/search", response_model=SearchResponse)
+async def semantic_search(request: SemanticSearchRequest):
+    """
+    Semantic search in indexed documents.
+    
+    Uses hybrid RAG (FAISS + BM25 + reranking + LLM).
+    Returns a summary answering the query with citations.
+    """
+    try:
+        if not aethermap.current_job_id:
+            raise HTTPException(status_code=400, detail="Nenhum documento indexado. Use /index primeiro.")
+        
+        result = await aethermap.semantic_search(
+            query=request.query,
+            turbo_mode=request.turbo_mode
+        )
+        
+        return SearchResponse(
+            summary=result.summary,
+            results=result.results
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/entities", response_model=EntityGraphResponse)
+async def extract_entities():
+    """
+    Extract named entities (NER) from indexed documents.
+    
+    Returns:
+    - Hub entities (most connected)
+    - Relationship insights
+    - Graph metrics
+    """
+    try:
+        if not aethermap.current_job_id:
+            raise HTTPException(status_code=400, detail="Nenhum documento indexado. Use /index primeiro.")
+        
+        result = await aethermap.extract_entities()
+        
+        return EntityGraphResponse(
+            hubs=result.hubs,
+            insights=result.insights,
+            node_count=len(result.nodes),
+            edge_count=len(result.edges)
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/analyze")
+async def analyze_graph():
+    """
+    Analyze entity graph using LLM.
+    
+    Returns semantic insights about relationships and patterns.
+    """
+    try:
+        if not aethermap.current_job_id:
+            raise HTTPException(status_code=400, detail="Nenhum documento indexado. Use /index primeiro.")
+        
+        result = await aethermap.analyze_graph()
+        
+        return {
+            "analysis": result.analysis,
+            "key_entities": result.key_entities,
+            "relationships": result.relationships
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/describe-clusters")
+async def describe_clusters():
+    """
+    Get LLM descriptions for each cluster found.
+    """
+    try:
+        if not aethermap.current_job_id:
+            raise HTTPException(status_code=400, detail="Nenhum documento indexado. Use /index primeiro.")
+        
+        result = await aethermap.describe_clusters()
+        
+        return result
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

app/api/routes/analyze.py

@@ -0,0 +1,309 @@
+"""
+Analyze API Routes - LLM-based text analysis
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from sqlalchemy.orm import Session
+import traceback
+
+from app.api.deps import get_scoped_db
+from app.services.nlp import entity_extractor
+from app.services.geocoding import geocode
+from app.models.entity import Entity, Relationship, Event
+from app.config import settings
+
+
+router = APIRouter(prefix="/analyze", tags=["Analysis"])
+
+
+class AnalyzeRequest(BaseModel):
+    """Request model for text analysis"""
+    text: str = Field(..., min_length=10, description="Text to analyze")
+    auto_create: bool = Field(default=False, description="Auto-create extracted entities in database")
+    
+
+class ExtractedEntityResponse(BaseModel):
+    """Response model for an extracted entity"""
+    name: str
+    type: str
+    role: Optional[str] = None
+    aliases: Optional[List[str]] = None
+    description: Optional[str] = None
+    created: bool = False  # Whether it was created in DB
+    entity_id: Optional[str] = None  # DB ID if created
+
+
+class ExtractedRelationshipResponse(BaseModel):
+    """Response model for an extracted relationship"""
+    source: str
+    target: str
+    relationship_type: str
+    context: Optional[str] = None
+    created: bool = False
+
+
+class ExtractedEventResponse(BaseModel):
+    """Response model for an extracted event"""
+    description: str
+    event_type: Optional[str] = None
+    date: Optional[str] = None
+    location: Optional[str] = None
+    participants: Optional[List[str]] = None
+    created: bool = False
+    event_id: Optional[str] = None
+
+
+class AnalyzeResponse(BaseModel):
+    """Response model for analysis"""
+    entities: List[ExtractedEntityResponse]
+    relationships: List[ExtractedRelationshipResponse]
+    events: List[ExtractedEventResponse]
+    stats: dict
+
+
+@router.post("", response_model=AnalyzeResponse)
+async def analyze_text(request: AnalyzeRequest, db: Session = Depends(get_scoped_db)):
+    """
+    Analyze text using LLM to extract entities, relationships, and events.
+    
+    Uses Cerebras API with Qwen 3 235B for intelligent extraction.
+    
+    Args:
+        text: Text to analyze (min 10 characters)
+        auto_create: If true, automatically creates entities in the database
+        
+    Returns:
+        Extracted entities, relationships, events, and statistics
+    """
+    try:
+        # Extract using LLM
+        result = await entity_extractor.extract(request.text)
+        
+        # Prepare response
+        entities_response = []
+        relationships_response = []
+        events_response = []
+        
+        created_entities = 0
+        created_relationships = 0
+        created_events = 0
+        
+        # Helper function to parse date strings
+        def parse_date(date_str):
+            if not date_str:
+                return None
+            from datetime import datetime
+            try:
+                # Try YYYY-MM-DD format
+                return datetime.strptime(date_str[:10], "%Y-%m-%d")
+            except:
+                try:
+                    # Try YYYY format
+                    return datetime.strptime(date_str[:4], "%Y")
+                except:
+                    return None
+        
+        # Process entities
+        for entity in result.entities:
+            entity_data = ExtractedEntityResponse(
+                name=entity.name,
+                type=entity.type,
+                role=entity.role,
+                aliases=entity.aliases,
+                description=entity.description,
+                created=False
+            )
+            
+            if request.auto_create and entity.name:
+                # Check if entity already exists
+                existing = db.query(Entity).filter(
+                    Entity.name.ilike(f"%{entity.name}%")
+                ).first()
+                
+                if not existing:
+                    # Get coordinates for location entities
+                    lat, lng = None, None
+                    if entity.type == "location":
+                        coords = await geocode(entity.name)
+                        if coords:
+                            lat, lng = coords
+                    
+                    # Parse event_date if available
+                    event_date = parse_date(getattr(entity, 'event_date', None))
+                    
+                    # Create new entity
+                    new_entity = Entity(
+                        name=entity.name,
+                        type=entity.type if entity.type in ["person", "organization", "location", "event"] else "person",
+                        description=entity.description or entity.role or "",
+                        source="llm_extraction",
+                        latitude=lat,
+                        longitude=lng,
+                        event_date=event_date,
+                        properties={"role": entity.role, "aliases": entity.aliases}
+                    )
+                    db.add(new_entity)
+                    db.commit()
+                    db.refresh(new_entity)
+                    
+                    entity_data.created = True
+                    entity_data.entity_id = new_entity.id
+                    created_entities += 1
+                else:
+                    entity_data.entity_id = existing.id
+            
+            entities_response.append(entity_data)
+        
+        # Process relationships
+        for rel in result.relationships:
+            rel_data = ExtractedRelationshipResponse(
+                source=rel.source,
+                target=rel.target,
+                relationship_type=rel.relationship_type,
+                context=rel.context,
+                created=False
+            )
+            
+            if request.auto_create:
+                # Find source and target entities
+                source_entity = db.query(Entity).filter(
+                    Entity.name.ilike(f"%{rel.source}%")
+                ).first()
+                target_entity = db.query(Entity).filter(
+                    Entity.name.ilike(f"%{rel.target}%")
+                ).first()
+                
+                if source_entity and target_entity:
+                    # Check if relationship exists
+                    existing_rel = db.query(Relationship).filter(
+                        Relationship.source_id == source_entity.id,
+                        Relationship.target_id == target_entity.id,
+                        Relationship.type == rel.relationship_type
+                    ).first()
+                    
+                    if not existing_rel:
+                        # Parse event_date if available
+                        rel_event_date = parse_date(getattr(rel, 'event_date', None))
+                        
+                        new_rel = Relationship(
+                            source_id=source_entity.id,
+                            target_id=target_entity.id,
+                            type=rel.relationship_type,
+                            event_date=rel_event_date,
+                            properties={"context": rel.context}
+                        )
+                        db.add(new_rel)
+                        db.commit()
+                        rel_data.created = True
+                        created_relationships += 1
+            
+            relationships_response.append(rel_data)
+        
+        # Process events
+        for event in result.events:
+            event_data = ExtractedEventResponse(
+                description=event.description,
+                event_type=event.event_type,
+                date=event.date,
+                location=event.location,
+                participants=event.participants,
+                created=False
+            )
+            
+            if request.auto_create and event.description:
+                # Create event
+                new_event = Event(
+                    title=event.description[:100] if len(event.description) > 100 else event.description,
+                    description=event.description,
+                    type=event.event_type or "general",
+                    source="llm_extraction"
+                )
+                db.add(new_event)
+                db.commit()
+                db.refresh(new_event)
+                
+                event_data.created = True
+                event_data.event_id = new_event.id
+                created_events += 1
+            
+            events_response.append(event_data)
+        
+        return AnalyzeResponse(
+            entities=entities_response,
+            relationships=relationships_response,
+            events=events_response,
+            stats={
+                "total_entities": len(entities_response),
+                "total_relationships": len(relationships_response),
+                "total_events": len(events_response),
+                "created_entities": created_entities,
+                "created_relationships": created_relationships,
+                "created_events": created_events
+            }
+        )
+        
+    except Exception as e:
+        # Log the full error with traceback
+        print(f"=== ANALYZE ERROR ===")
+        print(f"Error type: {type(e).__name__}")
+        print(f"Error message: {str(e)}")
+        print(f"Traceback:")
+        traceback.print_exc()
+        print(f"=== END ERROR ===")
+        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
+
+
+@router.get("/debug")
+async def debug_config():
+    """
+    Debug endpoint to check if API is configured correctly.
+    """
+    api_key = settings.cerebras_api_key
+    return {
+        "cerebras_api_key_configured": bool(api_key),
+        "cerebras_api_key_length": len(api_key) if api_key else 0,
+        "cerebras_api_key_preview": f"{api_key[:8]}...{api_key[-4:]}" if api_key and len(api_key) > 12 else "NOT SET"
+    }
+
+
+@router.post("/quick")
+async def quick_analyze(request: AnalyzeRequest):
+    """
+    Quick analysis without database operations.
+    Returns only extracted data without creating anything.
+    """
+    try:
+        result = await entity_extractor.extract(request.text)
+        
+        return {
+            "entities": [
+                {
+                    "name": e.name,
+                    "type": e.type,
+                    "role": e.role,
+                    "aliases": e.aliases
+                }
+                for e in result.entities
+            ],
+            "relationships": [
+                {
+                    "source": r.source,
+                    "target": r.target,
+                    "type": r.relationship_type,
+                    "context": r.context
+                }
+                for r in result.relationships
+            ],
+            "events": [
+                {
+                    "description": ev.description,
+                    "type": ev.event_type,
+                    "date": ev.date,
+                    "participants": ev.participants
+                }
+                for ev in result.events
+            ]
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")

app/api/routes/chat.py

@@ -0,0 +1,63 @@
+"""
+Chat API Routes - Intelligent chat with RAG
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from typing import Optional
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_scoped_db, get_session_id
+from app.services.chat import chat_service
+
+
+router = APIRouter(prefix="/chat", tags=["Chat"])
+
+
+class ChatRequest(BaseModel):
+    """Chat request model"""
+    message: str = Field(..., min_length=1, description="User message")
+    use_web: bool = Field(default=True, description="Include web search")
+    use_history: bool = Field(default=True, description="Use conversation history")
+
+
+class ChatResponse(BaseModel):
+    """Chat response model"""
+    answer: str
+    local_context_used: bool
+    web_context_used: bool
+    entities_found: int
+
+
+@router.post("", response_model=ChatResponse)
+async def chat(
+    request: ChatRequest,
+    db: Session = Depends(get_scoped_db),
+    session_id: Optional[str] = Depends(get_session_id)
+):
+    """
+    Send a message and get an intelligent response.
+
+    Uses:
+    - Local NUMIDIUM knowledge (entities/relationships)
+    - Lancer web search (if enabled)
+    - Cerebras LLM for synthesis
+    """
+    try:
+        result = await chat_service.chat(
+            message=request.message,
+            db=db,
+            use_web=request.use_web,
+            use_history=request.use_history,
+            session_id=session_id
+        )
+        return ChatResponse(**result)
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/clear")
+async def clear_history(session_id: Optional[str] = Depends(get_session_id)):
+    """Clear conversation history"""
+    chat_service.clear_history(session_id=session_id)
+    return {"message": "Historico limpo"}

app/api/routes/dados_publicos.py

@@ -0,0 +1,155 @@
+"""
+Public Data API Routes - IBGE and TSE data access
+"""
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+
+from app.services.ibge_api import (
+    listar_estados, 
+    listar_municipios, 
+    buscar_municipio,
+    enriquecer_localizacao
+)
+from app.services.tse_api import (
+    listar_eleicoes,
+    buscar_candidatos,
+    obter_candidato_detalhes,
+    buscar_politico
+)
+
+
+router = APIRouter(prefix="/dados", tags=["Public Data"])
+
+
+# ========== IBGE Endpoints ==========
+
+class EstadoResponse(BaseModel):
+    id: int
+    sigla: str
+    nome: str
+    regiao: str
+
+
+class MunicipioResponse(BaseModel):
+    id: int
+    nome: str
+    estado_sigla: str
+    estado_nome: str
+    regiao: str
+
+
+@router.get("/ibge/estados", response_model=List[EstadoResponse])
+async def get_estados():
+    """List all Brazilian states"""
+    estados = await listar_estados()
+    return [EstadoResponse(**e.__dict__) for e in estados]
+
+
+@router.get("/ibge/municipios/{uf}", response_model=List[MunicipioResponse])
+async def get_municipios(uf: str):
+    """List municipalities in a state"""
+    municipios = await listar_municipios(uf)
+    return [MunicipioResponse(**m.__dict__) for m in municipios]
+
+
+@router.get("/ibge/buscar")
+async def buscar_cidade(
+    nome: str = Query(..., min_length=2),
+    uf: Optional[str] = None
+):
+    """Search for a municipality by name"""
+    municipios = await buscar_municipio(nome, uf)
+    return [MunicipioResponse(**m.__dict__) for m in municipios]
+
+
+@router.get("/ibge/enriquecer")
+async def enriquecer_cidade(
+    cidade: str = Query(..., min_length=2),
+    uf: Optional[str] = None
+):
+    """Enrich a location name with IBGE data"""
+    return await enriquecer_localizacao(cidade, uf)
+
+
+# ========== TSE Endpoints ==========
+
+class EleicaoResponse(BaseModel):
+    id: int
+    ano: int
+    descricao: str
+    turno: int
+
+
+class CandidatoResponse(BaseModel):
+    id: int
+    nome: str
+    nome_urna: str
+    numero: str
+    cargo: str
+    partido_sigla: str
+    uf: str
+    municipio: str
+    situacao: str
+    total_bens: float
+
+
+class CandidatoDetalhadoResponse(BaseModel):
+    id: int
+    nome: str
+    nome_urna: str
+    numero: str
+    cargo: str
+    partido_sigla: str
+    partido_nome: str
+    uf: str
+    municipio: str
+    situacao: str
+    data_nascimento: str
+    genero: str
+    grau_instrucao: str
+    ocupacao: str
+    total_bens: float
+    bens: List[Dict[str, Any]]
+
+
+@router.get("/tse/eleicoes", response_model=List[EleicaoResponse])
+async def get_eleicoes():
+    """List available elections"""
+    eleicoes = await listar_eleicoes()
+    return [EleicaoResponse(**e.__dict__) for e in eleicoes]
+
+
+@router.get("/tse/candidatos")
+async def get_candidatos(
+    nome: str = Query(..., min_length=3),
+    ano: int = Query(default=2024),
+    uf: Optional[str] = None,
+    cargo: Optional[str] = None
+):
+    """Search for candidates by name"""
+    candidatos = await buscar_candidatos(nome, ano=ano, uf=uf, cargo=cargo)
+    return [CandidatoResponse(**c.__dict__) for c in candidatos]
+
+
+@router.get("/tse/candidato/{id_candidato}")
+async def get_candidato_detalhes(
+    id_candidato: int,
+    ano: int = Query(default=2024)
+):
+    """Get detailed candidate information including assets"""
+    candidato = await obter_candidato_detalhes(id_candidato, ano=ano)
+    
+    if not candidato:
+        raise HTTPException(status_code=404, detail="Candidato não encontrado")
+    
+    return CandidatoDetalhadoResponse(**candidato.__dict__)
+
+
+@router.get("/tse/politico")
+async def pesquisar_politico(nome: str = Query(..., min_length=3)):
+    """
+    Search for a politician across multiple elections.
+    Returns consolidated career information.
+    """
+    return await buscar_politico(nome)

app/api/routes/entities.py

@@ -0,0 +1,353 @@
+"""
+Entity CRUD Routes
+"""
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+from sqlalchemy import or_
+from typing import List, Optional
+
+from app.api.deps import get_scoped_db
+from app.models import Entity, Relationship
+from app.schemas import EntityCreate, EntityUpdate, EntityResponse, GraphData, GraphNode, GraphEdge
+
+router = APIRouter(prefix="/entities", tags=["Entities"])
+
+
+@router.get("", response_model=List[EntityResponse])
+def list_entities(
+    type: Optional[str] = None,
+    search: Optional[str] = None,
+    project_id: Optional[str] = None,
+    limit: int = Query(default=50, le=200),
+    offset: int = 0,
+    db: Session = Depends(get_scoped_db)
+):
+    """Lista todas as entidades com filtros opcionais"""
+    query = db.query(Entity)
+    
+    if project_id:
+        query = query.filter(Entity.project_id == project_id)
+    
+    if type:
+        query = query.filter(Entity.type == type)
+    
+    if search:
+        query = query.filter(
+            or_(
+                Entity.name.ilike(f"%{search}%"),
+                Entity.description.ilike(f"%{search}%")
+            )
+        )
+    
+    query = query.order_by(Entity.created_at.desc())
+    return query.offset(offset).limit(limit).all()
+
+
+@router.get("/types")
+def get_entity_types(db: Session = Depends(get_scoped_db)):
+    """Retorna todos os tipos de entidade únicos"""
+    types = db.query(Entity.type).distinct().all()
+    return [t[0] for t in types]
+
+
+@router.get("/suggest-merge")
+async def suggest_merge_candidates(
+    limit: int = Query(default=10, le=50),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Use LLM to find potential duplicate entities that could be merged.
+    Returns pairs of entities that might be the same.
+    """
+    import httpx
+    import json
+    import re
+    from app.config import settings
+    
+    # Get all entities
+    entities = db.query(Entity).order_by(Entity.name).limit(200).all()
+    
+    if len(entities) < 2:
+        return {"candidates": [], "message": "Not enough entities to compare"}
+    
+    # Build entity list for LLM
+    entity_list = []
+    for e in entities:
+        aliases = (e.properties or {}).get("aliases", [])
+        entity_list.append({
+            "id": e.id,
+            "name": e.name,
+            "type": e.type,
+            "aliases": aliases[:5] if aliases else []
+        })
+    
+    # Ask LLM to find duplicates
+    prompt = f"""Analise esta lista de entidades e encontre possíveis DUPLICATAS (mesma pessoa/organização/local com nomes diferentes).
+
+Entidades:
+{entity_list[:100]}
+
+Retorne APENAS um JSON válido com pares de IDs que são provavelmente a mesma entidade:
+```json
+{{
+  "duplicates": [
+    {{
+      "id1": "uuid1",
+      "id2": "uuid2", 
+      "confidence": 0.95,
+      "reason": "Mesmo nome com variação"
+    }}
+  ]
+}}
+```
+
+Se não houver duplicatas, retorne: {{"duplicates": []}}
+"""
+    
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(
+                "https://api.cerebras.ai/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {settings.cerebras_api_key}",
+                    "Content-Type": "application/json"
+                },
+                json={
+                    "model": "zai-glm-4.7",
+                    "messages": [
+                        {"role": "system", "content": "Você é um especialista em detecção de entidades duplicadas. Responda apenas em JSON válido."},
+                        {"role": "user", "content": prompt}
+                    ],
+                    "temperature": 0.1,
+                    "max_tokens": 1024
+                }
+            )
+            
+            if response.status_code != 200:
+                return {"candidates": [], "error": "LLM API error"}
+            
+            data = response.json()
+            content = data["choices"][0]["message"]["content"]
+            
+            # Parse JSON from response
+            json_match = re.search(r'\{.*\}', content, re.DOTALL)
+            if json_match:
+                result = json.loads(json_match.group(0))
+                
+                # Enrich with entity names
+                candidates = []
+                for dup in result.get("duplicates", [])[:limit]:
+                    e1 = next((e for e in entities if e.id == dup.get("id1")), None)
+                    e2 = next((e for e in entities if e.id == dup.get("id2")), None)
+                    if e1 and e2:
+                        candidates.append({
+                            "entity1": {"id": e1.id, "name": e1.name, "type": e1.type},
+                            "entity2": {"id": e2.id, "name": e2.name, "type": e2.type},
+                            "confidence": dup.get("confidence", 0.5),
+                            "reason": dup.get("reason", "Possível duplicata")
+                        })
+                
+                return {"candidates": candidates}
+            
+            return {"candidates": [], "message": "No duplicates found"}
+            
+    except Exception as e:
+        return {"candidates": [], "error": str(e)}
+
+
+@router.get("/{entity_id}", response_model=EntityResponse)
+def get_entity(entity_id: str, db: Session = Depends(get_scoped_db)):
+    """Busca uma entidade por ID"""
+    entity = db.query(Entity).filter(Entity.id == entity_id).first()
+    if not entity:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    return entity
+
+
+@router.post("", response_model=EntityResponse, status_code=201)
+def create_entity(entity: EntityCreate, db: Session = Depends(get_scoped_db)):
+    """Cria uma nova entidade"""
+    db_entity = Entity(**entity.model_dump())
+    db.add(db_entity)
+    db.commit()
+    db.refresh(db_entity)
+    return db_entity
+
+
+@router.put("/{entity_id}", response_model=EntityResponse)
+def update_entity(entity_id: str, entity: EntityUpdate, db: Session = Depends(get_scoped_db)):
+    """Atualiza uma entidade existente"""
+    db_entity = db.query(Entity).filter(Entity.id == entity_id).first()
+    if not db_entity:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    
+    update_data = entity.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(db_entity, field, value)
+    
+    db.commit()
+    db.refresh(db_entity)
+    return db_entity
+
+
+@router.delete("/{entity_id}")
+def delete_entity(entity_id: str, db: Session = Depends(get_scoped_db)):
+    """Deleta uma entidade"""
+    db_entity = db.query(Entity).filter(Entity.id == entity_id).first()
+    if not db_entity:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    
+    # Delete related relationships
+    db.query(Relationship).filter(
+        or_(
+            Relationship.source_id == entity_id,
+            Relationship.target_id == entity_id
+        )
+    ).delete()
+    
+    db.delete(db_entity)
+    db.commit()
+    return {"message": "Entity deleted"}
+
+
+@router.get("/{entity_id}/connections", response_model=GraphData)
+def get_entity_connections(
+    entity_id: str,
+    depth: int = Query(default=1, le=3),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Retorna o grafo de conexões de uma entidade
+    Usado para visualização de rede no frontend
+    """
+    entity = db.query(Entity).filter(Entity.id == entity_id).first()
+    if not entity:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    
+    nodes = {}
+    edges = []
+    visited = set()
+    
+    def explore(eid: str, current_depth: int):
+        if current_depth > depth or eid in visited:
+            return
+        visited.add(eid)
+        
+        e = db.query(Entity).filter(Entity.id == eid).first()
+        if not e:
+            return
+            
+        nodes[e.id] = GraphNode(
+            id=e.id,
+            type=e.type,
+            name=e.name,
+            properties=e.properties or {}
+        )
+        
+        # Outgoing relationships
+        for rel in db.query(Relationship).filter(Relationship.source_id == eid).all():
+            edges.append(GraphEdge(
+                source=rel.source_id,
+                target=rel.target_id,
+                type=rel.type,
+                confidence=rel.confidence
+            ))
+            explore(rel.target_id, current_depth + 1)
+        
+        # Incoming relationships
+        for rel in db.query(Relationship).filter(Relationship.target_id == eid).all():
+            edges.append(GraphEdge(
+                source=rel.source_id,
+                target=rel.target_id,
+                type=rel.type,
+                confidence=rel.confidence
+            ))
+            explore(rel.source_id, current_depth + 1)
+    
+    explore(entity_id, 0)
+    
+    return GraphData(
+        nodes=list(nodes.values()),
+        edges=edges
+    )
+
+
+@router.post("/merge")
+def merge_entities(
+    primary_id: str,
+    secondary_id: str,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Merge two entities into one.
+    The primary entity is kept, the secondary is deleted.
+    All relationships from secondary are transferred to primary.
+    """
+    if primary_id == secondary_id:
+        raise HTTPException(status_code=400, detail="Cannot merge entity with itself")
+    
+    primary = db.query(Entity).filter(Entity.id == primary_id).first()
+    secondary = db.query(Entity).filter(Entity.id == secondary_id).first()
+    
+    if not primary:
+        raise HTTPException(status_code=404, detail="Primary entity not found")
+    if not secondary:
+        raise HTTPException(status_code=404, detail="Secondary entity not found")
+    
+    # Merge properties
+    primary_props = primary.properties or {}
+    secondary_props = secondary.properties or {}
+    
+    # Add aliases from secondary
+    aliases = primary_props.get("aliases", []) or []
+    if secondary.name not in aliases:
+        aliases.append(secondary.name)
+    secondary_aliases = secondary_props.get("aliases", []) or []
+    for alias in secondary_aliases:
+        if alias not in aliases:
+            aliases.append(alias)
+    primary_props["aliases"] = aliases
+    
+    # Add merge history
+    merge_history = primary_props.get("merged_from", []) or []
+    merge_history.append({
+        "id": secondary.id,
+        "name": secondary.name,
+        "source": secondary.source
+    })
+    primary_props["merged_from"] = merge_history
+    
+    # Combine descriptions if primary has none
+    if not primary.description and secondary.description:
+        primary.description = secondary.description
+    
+    primary.properties = primary_props
+    
+    # Transfer relationships from secondary to primary
+    # Update source_id
+    db.query(Relationship).filter(
+        Relationship.source_id == secondary_id
+    ).update({"source_id": primary_id})
+    
+    # Update target_id
+    db.query(Relationship).filter(
+        Relationship.target_id == secondary_id
+    ).update({"target_id": primary_id})
+    
+    # Delete duplicate relationships (same source, target, type)
+    # This is a simple approach - in production you'd want more sophisticated deduplication
+    
+    # Delete the secondary entity
+    db.delete(secondary)
+    db.commit()
+    db.refresh(primary)
+    
+    return {
+        "message": f"Merged '{secondary.name}' into '{primary.name}'",
+        "primary": {
+            "id": primary.id,
+            "name": primary.name,
+            "aliases": aliases
+        }
+    }
+

app/api/routes/events.py

@@ -0,0 +1,113 @@
+"""
+Events CRUD Routes
+"""
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+from sqlalchemy import or_
+from typing import List, Optional
+from datetime import datetime
+
+from app.api.deps import get_scoped_db
+from app.models import Event
+from app.schemas import EventCreate, EventResponse
+
+router = APIRouter(prefix="/events", tags=["Events"])
+
+
+@router.get("/", response_model=List[EventResponse])
+def list_events(
+    type: Optional[str] = None,
+    search: Optional[str] = None,
+    start_date: Optional[datetime] = None,
+    end_date: Optional[datetime] = None,
+    limit: int = Query(default=50, le=200),
+    offset: int = 0,
+    db: Session = Depends(get_scoped_db)
+):
+    """Lista eventos com filtros opcionais"""
+    query = db.query(Event)
+
+    if type:
+        query = query.filter(Event.type == type)
+
+    if search:
+        query = query.filter(
+            or_(
+                Event.title.ilike(f"%{search}%"),
+                Event.description.ilike(f"%{search}%")
+            )
+        )
+
+    if start_date:
+        query = query.filter(Event.event_date >= start_date)
+    if end_date:
+        query = query.filter(Event.event_date <= end_date)
+
+    query = query.order_by(Event.event_date.desc().nullslast())
+    return query.offset(offset).limit(limit).all()
+
+
+@router.get("/types")
+def get_event_types(db: Session = Depends(get_scoped_db)):
+    """Retorna todos os tipos de evento unicos"""
+    types = db.query(Event.type).distinct().all()
+    return [t[0] for t in types]
+
+
+@router.get("/timeline")
+def get_timeline(
+    entity_id: Optional[str] = None,
+    limit: int = Query(default=50, le=200),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Retorna eventos em formato timeline.
+    """
+    query = db.query(Event).filter(Event.event_date.isnot(None))
+
+    if entity_id:
+        query = query.filter(Event.entity_ids.contains([entity_id]))
+
+    events = query.order_by(Event.event_date.asc()).limit(limit).all()
+
+    return [
+        {
+            "id": e.id,
+            "title": e.title,
+            "date": e.event_date.isoformat() if e.event_date else None,
+            "type": e.type,
+            "location": e.location_name
+        }
+        for e in events
+    ]
+
+
+@router.get("/{event_id}", response_model=EventResponse)
+def get_event(event_id: str, db: Session = Depends(get_scoped_db)):
+    """Busca um evento por ID"""
+    event = db.query(Event).filter(Event.id == event_id).first()
+    if not event:
+        raise HTTPException(status_code=404, detail="Event not found")
+    return event
+
+
+@router.post("/", response_model=EventResponse, status_code=201)
+def create_event(event: EventCreate, db: Session = Depends(get_scoped_db)):
+    """Cria um novo evento"""
+    db_event = Event(**event.model_dump())
+    db.add(db_event)
+    db.commit()
+    db.refresh(db_event)
+    return db_event
+
+
+@router.delete("/{event_id}")
+def delete_event(event_id: str, db: Session = Depends(get_scoped_db)):
+    """Deleta um evento"""
+    db_event = db.query(Event).filter(Event.id == event_id).first()
+    if not db_event:
+        raise HTTPException(status_code=404, detail="Event not found")
+
+    db.delete(db_event)
+    db.commit()
+    return {"message": "Event deleted"}

app/api/routes/graph.py

@@ -0,0 +1,173 @@
+"""
+Graph API Routes - Network visualization endpoints
+"""
+from fastapi import APIRouter, Depends, HTTPException, Query
+from typing import Optional, List
+from sqlalchemy.orm import Session
+from sqlalchemy import or_
+
+from app.api.deps import get_scoped_db
+from app.models.entity import Entity, Relationship
+
+
+router = APIRouter(prefix="/graph", tags=["Graph"])
+
+
+@router.get("")
+async def get_graph(
+    entity_type: Optional[str] = Query(None, description="Filter by entity type"),
+    limit: int = Query(100, le=500, description="Maximum number of entities"),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Get graph data for visualization.
+    Returns nodes (entities) and edges (relationships).
+    """
+    try:
+        # Get entities
+        query = db.query(Entity)
+        if entity_type:
+            query = query.filter(Entity.type == entity_type)
+        
+        entities = query.limit(limit).all()
+        entity_ids = [e.id for e in entities]
+        
+        # Get relationships between these entities
+        relationships = db.query(Relationship).filter(
+            or_(
+                Relationship.source_id.in_(entity_ids),
+                Relationship.target_id.in_(entity_ids)
+            )
+        ).all()
+        
+        # Format for Cytoscape.js
+        nodes = []
+        for e in entities:
+            nodes.append({
+                "data": {
+                    "id": e.id,
+                    "label": e.name[:30] + "..." if len(e.name) > 30 else e.name,
+                    "fullName": e.name,
+                    "type": e.type,
+                    "description": e.description[:100] if e.description else "",
+                    "source": e.source or "unknown"
+                }
+            })
+        
+        edges = []
+        for r in relationships:
+            if r.source_id in entity_ids and r.target_id in entity_ids:
+                edges.append({
+                    "data": {
+                        "id": r.id,
+                        "source": r.source_id,
+                        "target": r.target_id,
+                        "label": r.type,
+                        "type": r.type
+                    }
+                })
+        
+        return {
+            "nodes": nodes,
+            "edges": edges,
+            "stats": {
+                "total_nodes": len(nodes),
+                "total_edges": len(edges)
+            }
+        }
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get graph: {str(e)}")
+
+
+@router.get("/entity/{entity_id}")
+async def get_entity_graph(
+    entity_id: str,
+    depth: int = Query(1, ge=1, le=3, description="How many levels of connections to include"),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Get graph centered on a specific entity.
+    """
+    try:
+        # Get the central entity
+        central = db.query(Entity).filter(Entity.id == entity_id).first()
+        if not central:
+            raise HTTPException(status_code=404, detail="Entity not found")
+        
+        # Collect entity IDs at each depth level
+        collected_ids = {entity_id}
+        current_level = {entity_id}
+        
+        for _ in range(depth):
+            rels = db.query(Relationship).filter(
+                or_(
+                    Relationship.source_id.in_(current_level),
+                    Relationship.target_id.in_(current_level)
+                )
+            ).all()
+            
+            next_level = set()
+            for r in rels:
+                next_level.add(r.source_id)
+                next_level.add(r.target_id)
+            
+            current_level = next_level - collected_ids
+            collected_ids.update(next_level)
+        
+        # Get all entities
+        entities = db.query(Entity).filter(Entity.id.in_(collected_ids)).all()
+        
+        # Get all relationships between collected entities
+        relationships = db.query(Relationship).filter(
+            Relationship.source_id.in_(collected_ids),
+            Relationship.target_id.in_(collected_ids)
+        ).all()
+        
+        # Format for Cytoscape
+        nodes = []
+        for e in entities:
+            nodes.append({
+                "data": {
+                    "id": e.id,
+                    "label": e.name[:30] + "..." if len(e.name) > 30 else e.name,
+                    "fullName": e.name,
+                    "type": e.type,
+                    "description": e.description[:100] if e.description else "",
+                    "source": e.source or "unknown",
+                    "isCentral": e.id == entity_id
+                }
+            })
+        
+        edges = []
+        for r in relationships:
+            edges.append({
+                "data": {
+                    "id": r.id,
+                    "source": r.source_id,
+                    "target": r.target_id,
+                    "label": r.type,
+                    "type": r.type
+                }
+            })
+        
+        return {
+            "central": {
+                "id": central.id,
+                "name": central.name,
+                "type": central.type
+            },
+            "nodes": nodes,
+            "edges": edges,
+            "stats": {
+                "total_nodes": len(nodes),
+                "total_edges": len(edges),
+                "depth": depth
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get entity graph: {str(e)}")
+

app/api/routes/ingest.py

@@ -0,0 +1,341 @@
+"""
+Data Ingestion Routes
+Endpoints para importar dados de fontes externas
+"""
+from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks
+from sqlalchemy.orm import Session
+from typing import Optional, List
+from datetime import datetime
+import asyncio
+
+from app.api.deps import get_scoped_db
+from app.models import Entity, Document, Relationship
+from app.schemas import EntityResponse, DocumentResponse
+from app.services.ingestion import wikipedia_scraper, news_service
+from app.services.nlp import entity_extractor
+from app.services.geocoding import geocode
+
+router = APIRouter(prefix="/ingest", tags=["Data Ingestion"])
+
+
+def parse_event_date(date_str):
+    """Parse date string to datetime object"""
+    if not date_str:
+        return None
+    try:
+        # Try YYYY-MM-DD format
+        return datetime.strptime(date_str[:10], "%Y-%m-%d")
+    except:
+        try:
+            # Try YYYY format
+            return datetime.strptime(date_str[:4], "%Y")
+        except:
+            return None
+
+
+# ========== Wikipedia ==========
+
+@router.get("/wikipedia/search")
+def search_wikipedia(q: str, limit: int = 10):
+    """Busca artigos na Wikipedia"""
+    results = wikipedia_scraper.search(q, limit)
+    return results
+
+
+@router.post("/wikipedia/entity", response_model=EntityResponse)
+async def import_from_wikipedia(
+    title: str,
+    entity_type: str = "person",
+    project_id: Optional[str] = None,
+    auto_extract: bool = True,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Importa uma entidade da Wikipedia
+    entity_type: person, organization, location
+    project_id: ID do projeto para associar a entidade
+    auto_extract: Se True, usa LLM para extrair entidades relacionadas
+    """
+    # Check if entity already exists
+    existing = db.query(Entity).filter(
+        Entity.name == title,
+        Entity.source == "wikipedia"
+    ).first()
+    
+    if existing:
+        return existing
+    
+    # Scrape based on type
+    if entity_type == "person":
+        data = wikipedia_scraper.scrape_person(title)
+    elif entity_type == "organization":
+        data = wikipedia_scraper.scrape_organization(title)
+    elif entity_type == "location":
+        data = wikipedia_scraper.scrape_location(title)
+    else:
+        data = wikipedia_scraper.scrape_person(title)  # default
+    
+    if not data:
+        raise HTTPException(status_code=404, detail="Article not found on Wikipedia")
+    
+    # Create main entity with project_id
+    entity = Entity(**data)
+    entity.project_id = project_id
+    db.add(entity)
+    db.commit()
+    db.refresh(entity)
+    
+    # Auto-extract entities and relationships using LLM
+    if auto_extract and data.get("description"):
+        try:
+            # Limit text to avoid token limits
+            text_to_analyze = data["description"][:3000]
+            result = await entity_extractor.extract(text_to_analyze)
+            
+            # Create extracted entities
+            created_entities = {}
+            for ext_entity in result.entities:
+                # Skip if same as main entity
+                if ext_entity.name.lower() == title.lower():
+                    created_entities[ext_entity.name] = entity
+                    continue
+                
+                # Check if entity exists (by similar name)
+                existing_ent = db.query(Entity).filter(
+                    Entity.name.ilike(f"%{ext_entity.name}%")
+                ).first()
+                
+                if existing_ent:
+                    created_entities[ext_entity.name] = existing_ent
+                else:
+                    # Get coordinates for location entities
+                    lat, lng = None, None
+                    if ext_entity.type == "location":
+                        coords = await geocode(ext_entity.name)
+                        if coords:
+                            lat, lng = coords
+                    
+                    # Parse event_date
+                    event_date = parse_event_date(getattr(ext_entity, 'event_date', None))
+                    
+                    new_ent = Entity(
+                        name=ext_entity.name,
+                        type=ext_entity.type if ext_entity.type in ["person", "organization", "location", "event"] else "person",
+                        description=ext_entity.description or ext_entity.role,
+                        source="wikipedia_extraction",
+                        latitude=lat,
+                        longitude=lng,
+                        event_date=event_date,
+                        project_id=project_id,
+                        properties={"role": ext_entity.role, "aliases": ext_entity.aliases, "extracted_from": title}
+                    )
+                    db.add(new_ent)
+                    db.commit()
+                    db.refresh(new_ent)
+                    created_entities[ext_entity.name] = new_ent
+            
+            # Create relationships
+            for rel in result.relationships:
+                source_ent = created_entities.get(rel.source) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.source}%")).first()
+                target_ent = created_entities.get(rel.target) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.target}%")).first()
+                
+                if source_ent and target_ent and source_ent.id != target_ent.id:
+                    # Check if relationship exists
+                    existing_rel = db.query(Relationship).filter(
+                        Relationship.source_id == source_ent.id,
+                        Relationship.target_id == target_ent.id,
+                        Relationship.type == rel.relationship_type
+                    ).first()
+                    
+                    if not existing_rel:
+                        # Parse relationship event_date
+                        rel_event_date = parse_event_date(getattr(rel, 'event_date', None))
+                        
+                        new_rel = Relationship(
+                            source_id=source_ent.id,
+                            target_id=target_ent.id,
+                            type=rel.relationship_type,
+                            event_date=rel_event_date,
+                            properties={"context": rel.context, "extracted_from": title}
+                        )
+                        db.add(new_rel)
+            
+            db.commit()
+            
+        except Exception as e:
+            print(f"NER extraction error: {e}")
+            # Continue without extraction if it fails
+    
+    return entity
+
+
+# ========== News ==========
+
+@router.get("/news/feeds")
+def list_available_feeds():
+    """Lista os feeds de notícias disponíveis"""
+    return list(news_service.RSS_FEEDS.keys())
+
+
+@router.get("/news/fetch")
+def fetch_news(feed: Optional[str] = None):
+    """
+    Busca notícias dos feeds RSS
+    Se feed não for especificado, busca de todos
+    """
+    if feed:
+        if feed not in news_service.RSS_FEEDS:
+            raise HTTPException(status_code=404, detail="Feed not found")
+        url = news_service.RSS_FEEDS[feed]
+        articles = news_service.fetch_feed(url)
+    else:
+        articles = news_service.fetch_all_feeds()
+    
+    return articles
+
+
+@router.get("/news/search")
+def search_news(q: str):
+    """Busca notícias por palavra-chave via Google News"""
+    return news_service.search_news(q)
+
+
+@router.post("/news/import")
+async def import_news(
+    query: Optional[str] = None,
+    feed: Optional[str] = None,
+    auto_extract: bool = True,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Importa notícias como documentos no sistema
+    auto_extract: Se True, usa LLM para extrair entidades de cada notícia
+    """
+    if query:
+        articles = news_service.search_news(query)
+    elif feed:
+        if feed not in news_service.RSS_FEEDS:
+            raise HTTPException(status_code=404, detail="Feed not found")
+        articles = news_service.fetch_feed(news_service.RSS_FEEDS[feed])
+    else:
+        articles = news_service.fetch_all_feeds()
+    
+    imported = 0
+    extracted_entities = 0
+    
+    for article in articles:
+        # Check if document already exists (by URL)
+        if article.get("url"):
+            existing = db.query(Document).filter(
+                Document.source_url == article["url"]
+            ).first()
+            if existing:
+                continue
+        
+        doc_data = news_service.to_document(article)
+        doc = Document(**doc_data)
+        db.add(doc)
+        db.commit()
+        imported += 1
+        
+        # Extract entities from article content
+        if auto_extract:
+            try:
+                text_to_analyze = f"{article.get('title', '')} {article.get('description', '')}".strip()
+                if len(text_to_analyze) >= 20:
+                    result = await entity_extractor.extract(text_to_analyze[:2000])
+                    
+                    created_entities = {}
+                    for ext_entity in result.entities:
+                        # Check if entity exists
+                        existing_ent = db.query(Entity).filter(
+                            Entity.name.ilike(f"%{ext_entity.name}%")
+                        ).first()
+                        
+                        if existing_ent:
+                            created_entities[ext_entity.name] = existing_ent
+                        else:
+                            # Get coordinates for location entities
+                            lat, lng = None, None
+                            if ext_entity.type == "location":
+                                coords = await geocode(ext_entity.name)
+                                if coords:
+                                    lat, lng = coords
+                            
+                            new_ent = Entity(
+                                name=ext_entity.name,
+                                type=ext_entity.type if ext_entity.type in ["person", "organization", "location", "event"] else "person",
+                                description=ext_entity.description or ext_entity.role,
+                                source="news_extraction",
+                                latitude=lat,
+                                longitude=lng,
+                                properties={"role": ext_entity.role, "aliases": ext_entity.aliases, "from_article": article.get('title', '')}
+                            )
+                            db.add(new_ent)
+                            db.commit()
+                            db.refresh(new_ent)
+                            created_entities[ext_entity.name] = new_ent
+                            extracted_entities += 1
+                    
+                    # Create relationships
+                    for rel in result.relationships:
+                        source_ent = created_entities.get(rel.source) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.source}%")).first()
+                        target_ent = created_entities.get(rel.target) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.target}%")).first()
+                        
+                        if source_ent and target_ent and source_ent.id != target_ent.id:
+                            existing_rel = db.query(Relationship).filter(
+                                Relationship.source_id == source_ent.id,
+                                Relationship.target_id == target_ent.id,
+                                Relationship.type == rel.relationship_type
+                            ).first()
+                            
+                            if not existing_rel:
+                                new_rel = Relationship(
+                                    source_id=source_ent.id,
+                                    target_id=target_ent.id,
+                                    type=rel.relationship_type,
+                                    properties={"context": rel.context}
+                                )
+                                db.add(new_rel)
+                    
+                    db.commit()
+                    
+            except Exception as e:
+                print(f"NER extraction error for article: {e}")
+                # Continue without extraction
+    
+    return {
+        "message": f"Imported {imported} articles", 
+        "total_found": len(articles),
+        "extracted_entities": extracted_entities
+    }
+
+
+# ========== Manual Import ==========
+
+@router.post("/bulk/entities")
+def bulk_import_entities(
+    entities: List[dict],
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Importa múltiplas entidades de uma vez
+    Útil para importar de CSV/JSON
+    """
+    imported = 0
+    for entity_data in entities:
+        entity = Entity(
+            type=entity_data.get("type", "unknown"),
+            name=entity_data.get("name", "Unnamed"),
+            description=entity_data.get("description"),
+            properties=entity_data.get("properties", {}),
+            latitude=entity_data.get("latitude"),
+            longitude=entity_data.get("longitude"),
+            source=entity_data.get("source", "manual")
+        )
+        db.add(entity)
+        imported += 1
+    
+    db.commit()
+    
+    return {"message": f"Imported {imported} entities"}

app/api/routes/investigate.py

@@ -0,0 +1,207 @@
+"""
+Investigation API Routes - Build dossiers on companies and people
+"""
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+from sqlalchemy.orm import Session
+
+from app.services.investigation import (
+    investigar_empresa,
+    investigar_pessoa,
+    dossier_to_dict
+)
+from app.services.brazil_apis import consultar_cnpj
+from app.services.investigator_agent import investigator_agent
+from app.api.deps import get_scoped_db
+
+
+router = APIRouter(prefix="/investigate", tags=["Investigation"])
+
+
+class InvestigateCompanyRequest(BaseModel):
+    """Request to investigate a company"""
+    cnpj: str = Field(..., min_length=11, description="CNPJ da empresa")
+
+
+class InvestigatePersonRequest(BaseModel):
+    """Request to investigate a person"""
+    nome: str = Field(..., min_length=2, description="Nome da pessoa")
+    cpf: Optional[str] = Field(None, description="CPF (opcional)")
+
+
+class DossierResponse(BaseModel):
+    """Dossier response"""
+    tipo: str
+    alvo: str
+    cnpj_cpf: Optional[str]
+    red_flags: List[str]
+    score_risco: int
+    data_geracao: str
+    fonte_dados: List[str]
+    secoes: Dict[str, Any]
+
+
+class CNPJResponse(BaseModel):
+    """Quick CNPJ lookup response"""
+    cnpj: str
+    razao_social: str
+    nome_fantasia: str
+    situacao: str
+    data_abertura: str
+    capital_social: float
+    endereco: str
+    telefone: str
+    email: str
+    atividade: str
+    socios: List[Dict[str, Any]]
+
+
+@router.post("/company", response_model=DossierResponse)
+async def investigate_company(request: InvestigateCompanyRequest):
+    """
+    Build a comprehensive dossier on a company.
+    
+    Collects:
+    - Cadastral data from CNPJ
+    - Partners/owners
+    - Sanctions (CEIS, CNEP, CEPIM)
+    - News and media mentions
+    - Related entities
+    
+    Returns risk score and red flags.
+    """
+    try:
+        dossier = await investigar_empresa(request.cnpj)
+        return DossierResponse(**dossier_to_dict(dossier))
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/person", response_model=DossierResponse)
+async def investigate_person(request: InvestigatePersonRequest):
+    """
+    Build a dossier on a person.
+    
+    Note: Due to LGPD, personal data is limited.
+    Mainly uses web search for public information.
+    """
+    try:
+        dossier = await investigar_pessoa(request.nome, request.cpf)
+        return DossierResponse(**dossier_to_dict(dossier))
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/cnpj/{cnpj}", response_model=CNPJResponse)
+async def lookup_cnpj(cnpj: str):
+    """
+    Quick CNPJ lookup - returns basic company data.
+    """
+    try:
+        data = await consultar_cnpj(cnpj)
+        
+        if not data:
+            raise HTTPException(status_code=404, detail="CNPJ não encontrado")
+        
+        return CNPJResponse(
+            cnpj=data.cnpj,
+            razao_social=data.razao_social,
+            nome_fantasia=data.nome_fantasia,
+            situacao=data.situacao,
+            data_abertura=data.data_abertura,
+            capital_social=data.capital_social,
+            endereco=f"{data.logradouro}, {data.numero} - {data.bairro}, {data.cidade}/{data.uf}",
+            telefone=data.telefone,
+            email=data.email,
+            atividade=f"{data.cnae_principal} - {data.cnae_descricao}",
+            socios=data.socios
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ===========================================
+# Autonomous Investigation Agent
+# ===========================================
+
+class AgentInvestigateRequest(BaseModel):
+    """Request for autonomous investigation"""
+    mission: str = Field(..., min_length=5, description="Missão de investigação em linguagem natural")
+    max_iterations: int = Field(10, ge=1, le=20, description="Máximo de iterações do agente")
+
+
+class FindingResponse(BaseModel):
+    """A finding from investigation"""
+    title: str
+    content: str
+    source: str
+    timestamp: str
+
+
+class AgentInvestigateResponse(BaseModel):
+    """Response from autonomous investigation"""
+    mission: str
+    status: str
+    report: str
+    findings: List[FindingResponse]
+    entities_discovered: int
+    connections_mapped: int
+    iterations: int
+    tools_used: List[str]
+
+
+@router.post("/agent", response_model=AgentInvestigateResponse)
+async def investigate_with_agent(
+    request: AgentInvestigateRequest,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Autonomous investigation with AI agent.
+    
+    The agent will:
+    1. Search NUMIDIUM for existing entities
+    2. Query CNPJ data for Brazilian companies
+    3. Search the web for news and public info
+    4. Follow leads and connections
+    5. Generate a comprehensive report
+    
+    Example missions:
+    - "Investigue a rede de empresas de João Silva"
+    - "Descubra os sócios da empresa CNPJ 11.222.333/0001-44"
+    - "Pesquise sobre a empresa XYZ e suas conexões"
+    """
+    try:
+        result = await investigator_agent.investigate(
+            mission=request.mission,
+            db=db,
+            max_iterations=request.max_iterations
+        )
+        
+        return AgentInvestigateResponse(
+            mission=result.mission,
+            status=result.status,
+            report=result.report,
+            findings=[
+                FindingResponse(
+                    title=f.title,
+                    content=f.content,
+                    source=f.source,
+                    timestamp=f.timestamp
+                )
+                for f in result.findings
+            ],
+            entities_discovered=len(result.entities_discovered),
+            connections_mapped=len(result.connections_mapped),
+            iterations=result.iterations,
+            tools_used=result.tools_used
+        )
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+

app/api/routes/projects.py

@@ -0,0 +1,135 @@
+"""
+Projects API Routes - Workspace management
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from typing import Optional, List
+from datetime import datetime
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_scoped_db
+from app.models import Project, Entity, Relationship
+
+
+router = APIRouter(prefix="/projects", tags=["Projects"])
+
+
+class ProjectCreate(BaseModel):
+    name: str
+    description: Optional[str] = None
+    color: str = "#00d4ff"
+    icon: str = "folder"
+
+
+class ProjectResponse(BaseModel):
+    id: str
+    name: str
+    description: Optional[str]
+    color: str
+    icon: str
+    entity_count: int = 0
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+@router.get("", response_model=List[ProjectResponse])
+def list_projects(db: Session = Depends(get_scoped_db)):
+    """List all projects"""
+    projects = db.query(Project).order_by(Project.created_at.desc()).all()
+    
+    result = []
+    for p in projects:
+        entity_count = db.query(Entity).filter(Entity.project_id == p.id).count()
+        result.append(ProjectResponse(
+            id=p.id,
+            name=p.name,
+            description=p.description,
+            color=p.color,
+            icon=p.icon,
+            entity_count=entity_count,
+            created_at=p.created_at
+        ))
+    
+    return result
+
+
+@router.post("", response_model=ProjectResponse)
+def create_project(project: ProjectCreate, db: Session = Depends(get_scoped_db)):
+    """Create a new project"""
+    new_project = Project(
+        name=project.name,
+        description=project.description,
+        color=project.color,
+        icon=project.icon
+    )
+    db.add(new_project)
+    db.commit()
+    db.refresh(new_project)
+    
+    return ProjectResponse(
+        id=new_project.id,
+        name=new_project.name,
+        description=new_project.description,
+        color=new_project.color,
+        icon=new_project.icon,
+        entity_count=0,
+        created_at=new_project.created_at
+    )
+
+
+@router.get("/{project_id}", response_model=ProjectResponse)
+def get_project(project_id: str, db: Session = Depends(get_scoped_db)):
+    """Get project by ID"""
+    project = db.query(Project).filter(Project.id == project_id).first()
+    
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    
+    entity_count = db.query(Entity).filter(Entity.project_id == project_id).count()
+    
+    return ProjectResponse(
+        id=project.id,
+        name=project.name,
+        description=project.description,
+        color=project.color,
+        icon=project.icon,
+        entity_count=entity_count,
+        created_at=project.created_at
+    )
+
+
+@router.delete("/{project_id}")
+def delete_project(project_id: str, db: Session = Depends(get_scoped_db)):
+    """Delete project and optionally its entities"""
+    project = db.query(Project).filter(Project.id == project_id).first()
+    
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    
+    # Set entities and relationships to no project (null)
+    db.query(Entity).filter(Entity.project_id == project_id).update({"project_id": None})
+    db.query(Relationship).filter(Relationship.project_id == project_id).update({"project_id": None})
+    
+    db.delete(project)
+    db.commit()
+    
+    return {"message": f"Project '{project.name}' deleted"}
+
+
+@router.put("/{project_id}")
+def update_project(project_id: str, project: ProjectCreate, db: Session = Depends(get_scoped_db)):
+    """Update project"""
+    existing = db.query(Project).filter(Project.id == project_id).first()
+    
+    if not existing:
+        raise HTTPException(status_code=404, detail="Project not found")
+    
+    existing.name = project.name
+    existing.description = project.description
+    existing.color = project.color
+    existing.icon = project.icon
+    db.commit()
+    
+    return {"message": "Project updated"}

app/api/routes/relationships.py

@@ -0,0 +1,76 @@
+"""
+Relationship CRUD Routes
+"""
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+from typing import List, Optional
+
+from app.api.deps import get_scoped_db
+from app.models import Relationship, Entity
+from app.schemas import RelationshipCreate, RelationshipResponse
+
+router = APIRouter(prefix="/relationships", tags=["Relationships"])
+
+
+@router.get("/", response_model=List[RelationshipResponse])
+def list_relationships(
+    type: Optional[str] = None,
+    source_id: Optional[str] = None,
+    target_id: Optional[str] = None,
+    limit: int = Query(default=50, le=200),
+    db: Session = Depends(get_scoped_db)
+):
+    """Lista relacionamentos com filtros opcionais"""
+    query = db.query(Relationship)
+
+    if type:
+        query = query.filter(Relationship.type == type)
+    if source_id:
+        query = query.filter(Relationship.source_id == source_id)
+    if target_id:
+        query = query.filter(Relationship.target_id == target_id)
+
+    return query.limit(limit).all()
+
+
+@router.get("/types")
+def get_relationship_types(db: Session = Depends(get_scoped_db)):
+    """Retorna todos os tipos de relacionamento unicos"""
+    types = db.query(Relationship.type).distinct().all()
+    return [t[0] for t in types]
+
+
+@router.post("/", response_model=RelationshipResponse, status_code=201)
+def create_relationship(
+    rel: RelationshipCreate,
+    db: Session = Depends(get_scoped_db)
+):
+    """Cria um novo relacionamento entre entidades"""
+    source = db.query(Entity).filter(Entity.id == rel.source_id).first()
+    target = db.query(Entity).filter(Entity.id == rel.target_id).first()
+
+    if not source:
+        raise HTTPException(status_code=404, detail="Source entity not found")
+    if not target:
+        raise HTTPException(status_code=404, detail="Target entity not found")
+
+    db_rel = Relationship(**rel.model_dump())
+    db.add(db_rel)
+    db.commit()
+    db.refresh(db_rel)
+    return db_rel
+
+
+@router.delete("/{relationship_id}")
+def delete_relationship(
+    relationship_id: str,
+    db: Session = Depends(get_scoped_db)
+):
+    """Deleta um relacionamento"""
+    db_rel = db.query(Relationship).filter(Relationship.id == relationship_id).first()
+    if not db_rel:
+        raise HTTPException(status_code=404, detail="Relationship not found")
+
+    db.delete(db_rel)
+    db.commit()
+    return {"message": "Relationship deleted"}

app/api/routes/research.py

@@ -0,0 +1,158 @@
+"""
+Research API Routes - Deep research with automatic entity extraction
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from typing import Optional, List
+import traceback
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_scoped_db
+from app.services import lancer
+from app.services.nlp import entity_extractor
+from app.services.geocoding import geocode
+from app.models.entity import Entity, Relationship
+
+
+router = APIRouter(prefix="/research", tags=["Research"])
+
+
+class ResearchRequest(BaseModel):
+    """Request model for research"""
+    query: str = Field(..., min_length=3, description="Research query")
+    mode: str = Field(default="search", description="Research mode: search, deep, heavy")
+    max_results: int = Field(default=10, le=20)
+    auto_extract: bool = Field(default=True, description="Auto-extract entities using NER")
+
+
+class ResearchResponse(BaseModel):
+    """Response model for research"""
+    query: str
+    answer: Optional[str]
+    sources: List[dict]
+    citations: List[dict]
+    extracted_entities: int
+    extracted_relationships: int
+    processing_time_ms: float
+
+
+@router.post("", response_model=ResearchResponse)
+async def research(request: ResearchRequest, db: Session = Depends(get_scoped_db)):
+    """
+    Perform AI-powered research using Lancer API and optionally extract entities.
+    
+    Modes:
+    - search: Fast search with AI synthesis
+    - deep: Multi-dimensional deep research (slower, more comprehensive)
+    - heavy: Search with full content scraping
+    """
+    try:
+        # Call Lancer API based on mode
+        if request.mode == "deep":
+            result = await lancer.deep_research(request.query)
+        elif request.mode == "heavy":
+            result = await lancer.heavy_search(request.query, request.max_results)
+        else:
+            result = await lancer.search(request.query, request.max_results)
+        
+        extracted_entities = 0
+        extracted_relationships = 0
+        
+        # Extract entities if enabled
+        if request.auto_extract and result.raw_text:
+            try:
+                # Limit text to avoid token limits
+                text_to_analyze = result.raw_text[:5000]
+                ner_result = await entity_extractor.extract(text_to_analyze)
+                
+                created_entities = {}
+                
+                # Create entities
+                for entity in ner_result.entities:
+                    # Check if exists
+                    existing = db.query(Entity).filter(
+                        Entity.name.ilike(f"%{entity.name}%")
+                    ).first()
+                    
+                    if existing:
+                        created_entities[entity.name] = existing
+                    else:
+                        # Geocode if location
+                        lat, lng = None, None
+                        if entity.type == "location":
+                            coords = await geocode(entity.name)
+                            if coords:
+                                lat, lng = coords
+                        
+                        new_entity = Entity(
+                            name=entity.name,
+                            type=entity.type if entity.type in ["person", "organization", "location", "event"] else "person",
+                            description=entity.description or entity.role or "",
+                            source="lancer_research",
+                            latitude=lat,
+                            longitude=lng,
+                            properties={
+                                "role": entity.role,
+                                "aliases": entity.aliases,
+                                "research_query": request.query
+                            }
+                        )
+                        db.add(new_entity)
+                        db.commit()
+                        db.refresh(new_entity)
+                        created_entities[entity.name] = new_entity
+                        extracted_entities += 1
+                
+                # Create relationships
+                for rel in ner_result.relationships:
+                    source_ent = created_entities.get(rel.source) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.source}%")).first()
+                    target_ent = created_entities.get(rel.target) or db.query(Entity).filter(Entity.name.ilike(f"%{rel.target}%")).first()
+                    
+                    if source_ent and target_ent and source_ent.id != target_ent.id:
+                        existing_rel = db.query(Relationship).filter(
+                            Relationship.source_id == source_ent.id,
+                            Relationship.target_id == target_ent.id,
+                            Relationship.type == rel.relationship_type
+                        ).first()
+                        
+                        if not existing_rel:
+                            new_rel = Relationship(
+                                source_id=source_ent.id,
+                                target_id=target_ent.id,
+                                type=rel.relationship_type,
+                                properties={"context": rel.context, "research_query": request.query}
+                            )
+                            db.add(new_rel)
+                            extracted_relationships += 1
+                
+                db.commit()
+                
+            except Exception as e:
+                print(f"NER extraction error: {e}")
+                traceback.print_exc()
+        
+        # Prepare sources for response
+        sources = [
+            {
+                "title": r.title,
+                "url": r.url,
+                "content": r.content[:300] if r.content else "",
+                "score": r.score
+            }
+            for r in result.results[:10]
+        ]
+        
+        return ResearchResponse(
+            query=result.query,
+            answer=result.answer,
+            sources=sources,
+            citations=result.citations,
+            extracted_entities=extracted_entities,
+            extracted_relationships=extracted_relationships,
+            processing_time_ms=result.processing_time_ms
+        )
+        
+    except Exception as e:
+        print(f"Research error: {e}")
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=str(e))

app/api/routes/search.py

@@ -0,0 +1,126 @@
+"""
+Search and Analytics Routes
+"""
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+from sqlalchemy import or_, func
+from typing import Optional
+
+from app.api.deps import get_scoped_db
+from app.models import Entity, Relationship, Event, Document
+from app.schemas import SearchResult, SystemStats
+
+router = APIRouter(prefix="/search", tags=["Search"])
+
+
+@router.get("", response_model=SearchResult)
+def global_search(
+    q: str = Query(..., min_length=2, description="Search query"),
+    types: Optional[str] = Query(None, description="Entity types (comma-separated)"),
+    limit: int = Query(default=20, le=100),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Busca global em todas as entidades, eventos e documentos.
+    """
+    search_term = f"%{q}%"
+    type_filter = types.split(",") if types else None
+
+    entity_query = db.query(Entity).filter(
+        or_(
+            Entity.name.ilike(search_term),
+            Entity.description.ilike(search_term)
+        )
+    )
+    if type_filter:
+        entity_query = entity_query.filter(Entity.type.in_(type_filter))
+    entities = entity_query.limit(limit).all()
+
+    events = db.query(Event).filter(
+        or_(
+            Event.title.ilike(search_term),
+            Event.description.ilike(search_term)
+        )
+    ).limit(limit).all()
+
+    documents = db.query(Document).filter(
+        or_(
+            Document.title.ilike(search_term),
+            Document.content.ilike(search_term)
+        )
+    ).limit(limit).all()
+
+    return SearchResult(
+        entities=entities,
+        events=events,
+        documents=documents
+    )
+
+
+@router.get("/stats", response_model=SystemStats)
+def get_system_stats(db: Session = Depends(get_scoped_db)):
+    """
+    Retorna estatisticas gerais do sistema.
+    """
+    total_entities = db.query(Entity).count()
+    total_relationships = db.query(Relationship).count()
+    total_events = db.query(Event).count()
+    total_documents = db.query(Document).count()
+
+    type_counts = db.query(
+        Entity.type,
+        func.count(Entity.id)
+    ).group_by(Entity.type).all()
+
+    entities_by_type = {t: c for t, c in type_counts}
+
+    recent = db.query(Entity).order_by(Entity.created_at.desc()).limit(10).all()
+    recent_activity = [
+        {
+            "id": e.id,
+            "type": e.type,
+            "name": e.name,
+            "created_at": e.created_at.isoformat()
+        }
+        for e in recent
+    ]
+
+    return SystemStats(
+        total_entities=total_entities,
+        total_relationships=total_relationships,
+        total_events=total_events,
+        total_documents=total_documents,
+        entities_by_type=entities_by_type,
+        recent_activity=recent_activity
+    )
+
+
+@router.get("/geo")
+def get_geo_data(
+    entity_type: Optional[str] = None,
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Retorna entidades com geolocalizacao.
+    """
+    query = db.query(Entity).filter(
+        Entity.latitude.isnot(None),
+        Entity.longitude.isnot(None)
+    )
+
+    if entity_type:
+        query = query.filter(Entity.type == entity_type)
+
+    entities = query.all()
+
+    return [
+        {
+            "id": e.id,
+            "type": e.type,
+            "name": e.name,
+            "lat": e.latitude,
+            "lng": e.longitude,
+            "properties": e.properties
+        }
+        for e in entities
+    ]

app/api/routes/session.py

@@ -0,0 +1,44 @@
+"""
+Session management routes
+"""
+from fastapi import APIRouter, Header, Cookie, Response, Request
+from typing import Optional
+import uuid
+
+from app.core.database import create_new_session_id
+from app.config import settings
+
+router = APIRouter(prefix="/session", tags=["Session"])
+
+
+@router.post("/create")
+def create_session(response: Response, request: Request):
+    """Create a new session and return session_id"""
+    session_id = create_new_session_id()
+    secure = settings.cookie_secure
+    samesite = settings.cookie_samesite
+    proto = request.headers.get("x-forwarded-proto", request.url.scheme)
+    if proto != "https" and secure:
+        secure = False
+        samesite = "lax"
+    response.set_cookie(
+        key="numidium_session",
+        value=session_id,
+        max_age=60*60*24*365,  # 1 year
+        httponly=True,
+        samesite=samesite,
+        secure=secure
+    )
+    return {"session_id": session_id}
+
+
+@router.get("/current")
+def get_current_session(
+    numidium_session: Optional[str] = Cookie(None),
+    x_session_id: Optional[str] = Header(None)
+):
+    """Get current session ID"""
+    session_id = x_session_id or numidium_session
+    if not session_id:
+        return {"session_id": None, "message": "No session. Call POST /session/create"}
+    return {"session_id": session_id}

app/api/routes/timeline.py

@@ -0,0 +1,165 @@
+"""
+Timeline API Routes - Temporal view of entities and relationships
+"""
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timedelta
+from collections import defaultdict
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_scoped_db
+from app.models.entity import Entity, Relationship
+
+
+router = APIRouter(prefix="/timeline", tags=["Timeline"])
+
+
+class TimelineEvent(BaseModel):
+    id: str
+    type: str  # "entity" or "relationship"
+    entity_type: Optional[str] = None
+    name: str
+    description: Optional[str] = None
+    date: str
+    icon: str
+
+
+class TimelineGroup(BaseModel):
+    date: str
+    label: str
+    events: List[TimelineEvent]
+
+
+class TimelineResponse(BaseModel):
+    groups: List[TimelineGroup]
+    total_events: int
+
+
+@router.get("", response_model=TimelineResponse)
+async def get_timeline(
+    days: int = Query(default=30, ge=1, le=365),
+    entity_type: Optional[str] = None,
+    limit: int = Query(default=100, ge=1, le=500),
+    db: Session = Depends(get_scoped_db)
+):
+    """
+    Get timeline of recent entities and relationships.
+    Groups events by date.
+    """
+    # Calculate date range
+    end_date = datetime.now()
+    start_date = end_date - timedelta(days=days)
+    
+    events = []
+    
+    # Get entities
+    query = db.query(Entity).filter(
+        Entity.created_at >= start_date
+    )
+    
+    if entity_type:
+        query = query.filter(Entity.type == entity_type)
+    
+    entities = query.order_by(Entity.created_at.desc()).limit(limit).all()
+    
+    icon_map = {
+        "person": "👤",
+        "organization": "🏢",
+        "location": "📍",
+        "event": "📅",
+        "concept": "💡",
+        "product": "📦"
+    }
+    
+    for e in entities:
+        # Prefer event_date over created_at
+        date = e.event_date if e.event_date else e.created_at
+        events.append(TimelineEvent(
+            id=e.id,
+            type="entity",
+            entity_type=e.type,
+            name=e.name,
+            description=e.description[:100] if e.description else None,
+            date=date.isoformat() if date else datetime.now().isoformat(),
+            icon=icon_map.get(e.type, "📄")
+        ))
+    
+    # Get relationships
+    relationships = db.query(Relationship).filter(
+        Relationship.created_at >= start_date
+    ).order_by(Relationship.created_at.desc()).limit(limit // 2).all()
+    
+    for r in relationships:
+        source = db.query(Entity).filter(Entity.id == r.source_id).first()
+        target = db.query(Entity).filter(Entity.id == r.target_id).first()
+        
+        if source and target:
+            # Prefer event_date over created_at
+            date = r.event_date if r.event_date else r.created_at
+            events.append(TimelineEvent(
+                id=r.id,
+                type="relationship",
+                name=f"{source.name} → {target.name}",
+                description=r.type,
+                date=date.isoformat() if date else datetime.now().isoformat(),
+                icon="🔗"
+            ))
+    
+    # Sort by date
+    events.sort(key=lambda x: x.date, reverse=True)
+    
+    # Group by date
+    groups_dict = defaultdict(list)
+    for event in events:
+        date_key = event.date[:10]  # YYYY-MM-DD
+        groups_dict[date_key].append(event)
+    
+    # Format groups
+    groups = []
+    for date_key in sorted(groups_dict.keys(), reverse=True):
+        try:
+            dt = datetime.fromisoformat(date_key)
+            label = dt.strftime("%d %b %Y")
+        except:
+            label = date_key
+        
+        groups.append(TimelineGroup(
+            date=date_key,
+            label=label,
+            events=groups_dict[date_key]
+        ))
+    
+    return TimelineResponse(
+        groups=groups,
+        total_events=len(events)
+    )
+
+
+@router.get("/stats")
+async def get_timeline_stats(db: Session = Depends(get_scoped_db)):
+    """Get statistics for timeline visualization"""
+    
+    # Count entities by type
+    entity_counts = {}
+    for entity_type in ["person", "organization", "location", "event", "concept"]:
+        count = db.query(Entity).filter(Entity.type == entity_type).count()
+        entity_counts[entity_type] = count
+    
+    # Count relationships
+    relationship_count = db.query(Relationship).count()
+    
+    # Recent activity (last 7 days)
+    week_ago = datetime.now() - timedelta(days=7)
+    recent_entities = db.query(Entity).filter(Entity.created_at >= week_ago).count()
+    recent_relationships = db.query(Relationship).filter(Relationship.created_at >= week_ago).count()
+    
+    return {
+        "entity_counts": entity_counts,
+        "relationship_count": relationship_count,
+        "recent_activity": {
+            "entities": recent_entities,
+            "relationships": recent_relationships,
+            "total": recent_entities + recent_relationships
+        }
+    }

app/config.py

@@ -0,0 +1,47 @@
+"""
+Numidium Backend Configuration
+"""
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+import os
+
+
+class Settings(BaseSettings):
+    """Application settings"""
+    
+    # App Info
+    app_name: str = "Numidium"
+    app_version: str = "0.1.0"
+    debug: bool = False
+    
+    # Database
+    database_url: str = "sqlite:///./data/numidium.db"
+    
+    # APIs (opcional - pode configurar depois)
+    newsapi_key: str = ""
+    
+    # Cerebras API for LLM-based entity extraction
+    cerebras_api_key: str = ""
+    
+    # AetherMap API for semantic search and NER
+    aethermap_url: str = "https://madras1-aethermap.hf.space"
+    
+    # CORS
+    cors_origins: list[str] = ["*"]
+
+    # Session cookie
+    cookie_secure: bool = True
+    cookie_samesite: str = "none"
+    
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached settings"""
+    return Settings()
+
+
+settings = get_settings()

app/core/__init__.py

@@ -0,0 +1,2 @@
+# Core module
+from app.core.database import get_db, init_db, Base

app/core/database.py

@@ -0,0 +1,115 @@
+"""
+Database configuration and session management
+Per-session databases - each user session gets its own SQLite file
+"""
+from sqlalchemy import create_engine, text
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker, Session
+from typing import Optional
+import os
+import uuid
+
+# Ensure data directory exists
+os.makedirs("data/sessions", exist_ok=True)
+
+# Base class for models
+Base = declarative_base()
+
+# Cache for session engines
+_session_engines = {}
+_session_makers = {}
+
+
+def get_session_engine(session_id: str):
+    """Get or create engine for a specific session"""
+    if session_id not in _session_engines:
+        db_path = f"data/sessions/{session_id}.db"
+        engine = create_engine(
+            f"sqlite:///./{db_path}",
+            connect_args={"check_same_thread": False}
+        )
+        _session_engines[session_id] = engine
+        _session_makers[session_id] = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+        
+        # Initialize tables for this session
+        Base.metadata.create_all(bind=engine)
+        _run_migrations(engine)
+        
+    return _session_engines[session_id]
+
+
+def get_session_db(session_id: str):
+    """Get database session for a specific user session"""
+    get_session_engine(session_id)  # Ensure engine exists
+    SessionLocal = _session_makers[session_id]
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def get_db_for_session(session_id: str) -> Session:
+    """Direct session getter (non-generator) for routes"""
+    get_session_engine(session_id)
+    SessionLocal = _session_makers[session_id]
+    return SessionLocal()
+
+
+# Legacy - default database for backwards compatibility
+from app.config import settings
+engine = create_engine(
+    settings.database_url,
+    connect_args={"check_same_thread": False}
+)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def get_default_session() -> Session:
+    """Create a new session for the default database."""
+    return SessionLocal()
+
+
+def get_db():
+    """Legacy: Default database session"""
+    db = get_default_session()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def _run_migrations(eng):
+    """Run migrations on an engine"""
+    with eng.connect() as conn:
+        try:
+            conn.execute(text("ALTER TABLE entities ADD COLUMN event_date DATETIME"))
+            conn.commit()
+        except Exception:
+            pass
+        try:
+            conn.execute(text("ALTER TABLE relationships ADD COLUMN event_date DATETIME"))
+            conn.commit()
+        except Exception:
+            pass
+        try:
+            conn.execute(text("ALTER TABLE entities ADD COLUMN project_id VARCHAR(36)"))
+            conn.commit()
+        except Exception:
+            pass
+        try:
+            conn.execute(text("ALTER TABLE relationships ADD COLUMN project_id VARCHAR(36)"))
+            conn.commit()
+        except Exception:
+            pass
+
+
+def init_db():
+    """Initialize default database tables"""
+    Base.metadata.create_all(bind=engine)
+    _run_migrations(engine)
+
+
+def create_new_session_id() -> str:
+    """Generate a new session ID"""
+    return str(uuid.uuid4())

app/main.py

@@ -0,0 +1,99 @@
+"""
+Numidium Backend - Main Application
+Plataforma de Inteligência e Análise de Dados
+"""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+
+from app.config import settings
+from app.core.database import init_db
+from app.api.routes import entities, relationships, events, search, ingest, analyze, graph, research, chat, investigate, dados_publicos, timeline, session, aethermap
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup and shutdown events"""
+    # Startup: Initialize database
+    init_db()
+    print("🚀 Numidium Backend started!")
+    print(f"📊 Database: {settings.database_url}")
+    yield
+    # Shutdown
+    print("👋 Numidium Backend shutting down...")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Numidium API",
+    description="""
+    ## 🔮 Sistema de Inteligência e Análise de Dados
+    
+    Backend do VANTAGE - Uma plataforma para:
+    - 📥 Ingestão de dados de múltiplas fontes (Wikipedia, News, Manual)
+    - 🔗 Mapeamento de conexões entre entidades
+    - 🗺️ Visualização geográfica
+    - 📊 Análise de grafos e relacionamentos
+    - 🔍 Busca global
+    """,
+    version=settings.app_version,
+    lifespan=lifespan
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(entities.router, prefix="/api/v1")
+app.include_router(relationships.router, prefix="/api/v1")
+app.include_router(events.router, prefix="/api/v1")
+app.include_router(search.router, prefix="/api/v1")
+app.include_router(ingest.router, prefix="/api/v1")
+app.include_router(analyze.router, prefix="/api/v1")
+app.include_router(graph.router, prefix="/api/v1")
+app.include_router(research.router, prefix="/api/v1")
+app.include_router(chat.router, prefix="/api/v1")
+app.include_router(investigate.router, prefix="/api/v1")
+app.include_router(dados_publicos.router, prefix="/api/v1")
+app.include_router(timeline.router, prefix="/api/v1")
+app.include_router(session.router, prefix="/api/v1")
+app.include_router(aethermap.router, prefix="/api/v1/aethermap", tags=["aethermap"])
+
+
+@app.get("/")
+def root():
+    """Root endpoint - API info"""
+    return {
+        "name": "Numidium",
+        "version": settings.app_version,
+        "status": "online",
+        "docs": "/docs",
+        "description": "Sistema de Inteligência e Análise de Dados"
+    }
+
+
+@app.get("/health")
+def health_check():
+    """Health check endpoint for HF Spaces"""
+    return {"status": "healthy"}
+
+
+@app.get("/api/v1")
+def api_info():
+    """API v1 info"""
+    return {
+        "version": "1.0.0",
+        "endpoints": {
+            "entities": "/api/v1/entities",
+            "relationships": "/api/v1/relationships",
+            "events": "/api/v1/events",
+            "search": "/api/v1/search",
+            "ingest": "/api/v1/ingest"
+        }
+    }

app/models/__init__.py

@@ -0,0 +1,3 @@
+# Models module
+from app.models.entity import Entity, Relationship, Event, Document
+from app.models.project import Project

app/models/entity.py

@@ -0,0 +1,143 @@
+"""
+SQLAlchemy Models for Numidium
+"""
+from sqlalchemy import Column, String, Text, DateTime, Float, JSON, ForeignKey, Table
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import uuid
+
+from app.core.database import Base
+
+
+def generate_uuid():
+    return str(uuid.uuid4())
+
+
+class Entity(Base):
+    """
+    Entidade - qualquer coisa rastreável no sistema
+    Pode ser: pessoa, organização, local, veículo, evento, documento, etc.
+    """
+    __tablename__ = "entities"
+    
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    project_id = Column(String(36), ForeignKey("projects.id"), nullable=True, index=True)
+    type = Column(String(50), nullable=False, index=True)  # person, organization, location, etc
+    name = Column(String(255), nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    properties = Column(JSON, default=dict)  # Dados flexíveis
+    
+    # Geolocalização (opcional)
+    latitude = Column(Float, nullable=True)
+    longitude = Column(Float, nullable=True)
+    
+    # Data histórica do evento/entidade (quando aconteceu, não quando foi adicionado)
+    event_date = Column(DateTime, nullable=True)
+    
+    # Fonte do dado
+    source = Column(String(100), nullable=True)  # wikipedia, newsapi, manual, etc
+    source_url = Column(Text, nullable=True)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relacionamentos
+    outgoing_relationships = relationship(
+        "Relationship",
+        foreign_keys="Relationship.source_id",
+        back_populates="source_entity"
+    )
+    incoming_relationships = relationship(
+        "Relationship",
+        foreign_keys="Relationship.target_id",
+        back_populates="target_entity"
+    )
+
+
+class Relationship(Base):
+    """
+    Relacionamento entre duas entidades
+    Exemplos: works_for, knows, owns, located_at, participated_in
+    """
+    __tablename__ = "relationships"
+    
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    project_id = Column(String(36), ForeignKey("projects.id"), nullable=True, index=True)
+    source_id = Column(String(36), ForeignKey("entities.id"), nullable=False)
+    target_id = Column(String(36), ForeignKey("entities.id"), nullable=False)
+    type = Column(String(50), nullable=False, index=True)  # works_for, knows, owns, etc
+    properties = Column(JSON, default=dict)
+    confidence = Column(Float, default=1.0)  # 0-1, quão certo estamos dessa conexão
+    
+    # Data histórica do relacionamento (quando aconteceu)
+    event_date = Column(DateTime, nullable=True)
+    
+    # Fonte
+    source = Column(String(100), nullable=True)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relacionamentos
+    source_entity = relationship("Entity", foreign_keys=[source_id], back_populates="outgoing_relationships")
+    target_entity = relationship("Entity", foreign_keys=[target_id], back_populates="incoming_relationships")
+
+
+class Event(Base):
+    """
+    Evento - algo que aconteceu envolvendo entidades
+    """
+    __tablename__ = "events"
+    
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    type = Column(String(50), nullable=False, index=True)
+    title = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    
+    # Quando aconteceu
+    event_date = Column(DateTime, nullable=True)
+    
+    # Onde aconteceu
+    location_name = Column(String(255), nullable=True)
+    latitude = Column(Float, nullable=True)
+    longitude = Column(Float, nullable=True)
+    
+    # Entidades envolvidas (armazenado como JSON array de IDs)
+    entity_ids = Column(JSON, default=list)
+    
+    # Fonte
+    source = Column(String(100), nullable=True)
+    source_url = Column(Text, nullable=True)
+    
+    # Metadados
+    properties = Column(JSON, default=dict)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class Document(Base):
+    """
+    Documento - texto/arquivo para análise
+    """
+    __tablename__ = "documents"
+    
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    title = Column(String(255), nullable=False)
+    content = Column(Text, nullable=True)
+    summary = Column(Text, nullable=True)  # Resumo gerado por IA
+    
+    # Tipo de documento
+    doc_type = Column(String(50), default="text")  # text, news, report, etc
+    
+    # Entidades mencionadas (extraídas por NLP)
+    mentioned_entities = Column(JSON, default=list)
+    
+    # Fonte
+    source = Column(String(100), nullable=True)
+    source_url = Column(Text, nullable=True)
+    
+    # Timestamps
+    published_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)

app/models/project.py

@@ -0,0 +1,29 @@
+"""
+Project Model - Workspaces for organizing investigations
+"""
+from sqlalchemy import Column, String, Text, DateTime
+from datetime import datetime
+import uuid
+
+from app.core.database import Base
+
+
+def generate_uuid():
+    return str(uuid.uuid4())
+
+
+class Project(Base):
+    """
+    Projeto/Workspace - agrupa entidades e relacionamentos por investigação
+    """
+    __tablename__ = "projects"
+    
+    id = Column(String(36), primary_key=True, default=generate_uuid)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    color = Column(String(7), default="#00d4ff")  # Hex color for UI
+    icon = Column(String(50), default="folder")  # Icon name
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

app/schemas/__init__.py

@@ -0,0 +1,10 @@
+# Schemas module
+from app.schemas.schemas import (
+    EntityCreate, EntityUpdate, EntityResponse,
+    RelationshipCreate, RelationshipResponse,
+    EventCreate, EventResponse,
+    DocumentCreate, DocumentResponse,
+    GraphData, GraphNode, GraphEdge,
+    SearchQuery, SearchResult,
+    SystemStats
+)

app/schemas/schemas.py

@@ -0,0 +1,163 @@
+"""
+Pydantic Schemas for API validation
+"""
+from pydantic import BaseModel, Field
+from typing import Optional, List, Any
+from datetime import datetime
+
+
+# ========== Entity Schemas ==========
+
+class EntityBase(BaseModel):
+    type: str = Field(..., description="Tipo da entidade: person, organization, location, etc")
+    name: str = Field(..., description="Nome da entidade")
+    description: Optional[str] = None
+    properties: dict = Field(default_factory=dict)
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    source: Optional[str] = None
+    source_url: Optional[str] = None
+
+
+class EntityCreate(EntityBase):
+    pass
+
+
+class EntityUpdate(BaseModel):
+    type: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    properties: Optional[dict] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+
+
+class EntityResponse(EntityBase):
+    id: str
+    created_at: datetime
+    updated_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# ========== Relationship Schemas ==========
+
+class RelationshipBase(BaseModel):
+    source_id: str
+    target_id: str
+    type: str = Field(..., description="Tipo: works_for, knows, owns, located_at, etc")
+    properties: dict = Field(default_factory=dict)
+    confidence: float = Field(default=1.0, ge=0, le=1)
+    source: Optional[str] = None
+
+
+class RelationshipCreate(RelationshipBase):
+    pass
+
+
+class RelationshipResponse(RelationshipBase):
+    id: str
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# ========== Event Schemas ==========
+
+class EventBase(BaseModel):
+    type: str
+    title: str
+    description: Optional[str] = None
+    event_date: Optional[datetime] = None
+    location_name: Optional[str] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    entity_ids: List[str] = Field(default_factory=list)
+    source: Optional[str] = None
+    source_url: Optional[str] = None
+    properties: dict = Field(default_factory=dict)
+
+
+class EventCreate(EventBase):
+    pass
+
+
+class EventResponse(EventBase):
+    id: str
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# ========== Document Schemas ==========
+
+class DocumentBase(BaseModel):
+    title: str
+    content: Optional[str] = None
+    doc_type: str = "text"
+    source: Optional[str] = None
+    source_url: Optional[str] = None
+    published_at: Optional[datetime] = None
+
+
+class DocumentCreate(DocumentBase):
+    pass
+
+
+class DocumentResponse(DocumentBase):
+    id: str
+    summary: Optional[str] = None
+    mentioned_entities: List[str] = []
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# ========== Graph Schemas ==========
+
+class GraphNode(BaseModel):
+    id: str
+    type: str
+    name: str
+    properties: dict = {}
+
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    type: str
+    confidence: float = 1.0
+
+
+class GraphData(BaseModel):
+    nodes: List[GraphNode]
+    edges: List[GraphEdge]
+
+
+# ========== Search Schemas ==========
+
+class SearchQuery(BaseModel):
+    query: str
+    entity_types: Optional[List[str]] = None
+    limit: int = Field(default=20, le=100)
+
+
+class SearchResult(BaseModel):
+    entities: List[EntityResponse]
+    events: List[EventResponse]
+    documents: List[DocumentResponse]
+
+
+# ========== Stats Schemas ==========
+
+class SystemStats(BaseModel):
+    total_entities: int
+    total_relationships: int
+    total_events: int
+    total_documents: int
+    entities_by_type: dict
+    recent_activity: List[dict]

app/services/__init__.py

@@ -0,0 +1 @@
+# Services module