RAG智能代理

# Clona il repository
git clone https://github.com/stefanopiga/Agent-RAG.git
cd Agent-RAG

# Installa le dipendenze usando UV
uv sync

cp .env.example .env

# RICHIESTO: Connessione database PostgreSQL con PGVector
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# RICHIESTO: OpenAI API key
OPENAI_API_KEY=sk-...

# OPZIONALE: Modello LLM (default: gpt-4o-mini)
LLM_CHOICE=gpt-4o-mini

# OPZIONALE: Modello embedding (default: text-embedding-3-small)
EMBEDDING_MODEL=text-embedding-3-small

# OPZIONALE: LangFuse per observability/tracing (MCP server)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# Esegui lo schema completo (include HNSW index ottimizzato)
# Per Supabase: Usa SQL Editor e incolla contenuto di optimize_index.sql
psql $DATABASE_URL < sql/optimize_index.sql

uv run python scripts/verification/optimize_database.py --apply

# Esegui schema Epic 3 (crea tabelle sessions e query_logs)
# Per Supabase: Usa SQL Editor e incolla contenuto di sql/epic-3-sessions-schema.sql
psql $DATABASE_URL < sql/epic-3-sessions-schema.sql

# Ingerisci tutti i documenti supportati nella cartella documents/
# NOTA: Di default, questo CANCELLA i dati esistenti prima dell'ingestione
uv run python -m ingestion.ingest --documents documents/

# Regola la dimensione dei chunk (default: 1000)
uv run python -m ingestion.ingest --documents documents/ --chunk-size 800

documents/
├── docling/
│   ├── docs/
│   │   ├── getting-started.md
│   │   └── architecture.md
│   └── README.md
├── langfuse-docs/
│   ├── deployment/
│   │   ├── cloud.md
│   │   └── docker.md
│   ├── api/
│   │   └── tracing.md
│   └── guides/
└── company-docs/
    ├── policies.pdf
    └── procedures.docx

# esegui api così accendi la parte sotto il cofano
uv run uvicorn api.main:app --host 0.0.0.0 --port 8000

# esegui streamlit cosi puoi interagire con l'UI
uv run streamlit run app.py

Tu: Quali argomenti sono trattati nella knowledge base?
Assistant: Sulla base della knowledge base, gli argomenti principali includono...

[Fonte: company-overview.md]
Contenuto dal documento...

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Streamlit  │────▶│  RAG Agent   │────▶│ PostgreSQL  │
│     UI      │     │ (PydanticAI) │     │  PGVector   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼────┐  ┌────▼─────┐
              │  OpenAI  │  │  OpenAI  │
              │   LLM    │  │Embeddings│
              └──────────┘  └──────────┘

async def search_knowledge_base(
    ctx: RunContext[None],
    query: str,
    limit: int = 5,
    source_filter: str | None = None  # Filtro opzionale per fonte
) -> str:
    """Cerca nella knowledge base usando similarità semantica.

    Args:
        query: Query di ricerca
        limit: Numero massimo risultati
        source_filter: Filtro opzionale (es: "docling", "langfuse-docs")
    """
    # Genera embedding per la query
    # Cerca in PostgreSQL con PGVector
    # Applica filtro fonte se specificato
    # Formatta e restituisce i risultati

# avvia il server mcp
uv run python mcp_server.py

# apri la porta locale http://localhost:8080/health
curl http://localhost:8080/health

{
  "mcpServers": {
    "docling-rag": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/docling-rag-agent",
        "python",
        "/path/to/docling-rag-agent/mcp_server.py"
      ]
    }
  }
}

Chiedi: "What is Docling?"
Il MCP tool cercherà nella knowledge base e risponderà con context

# LangFuse Configuration (opzionale)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Default, oppure URL self-hosted

scrape_configs:
  - job_name: "docling-rag-agent"
    scrape_interval: 15s # Default raccomandato (60s per cost-sensitive)
    static_configs:
      - targets: ["localhost:8080"]

# Avvia il server HTTP per metriche e health check (porta 8080)
uv run python -m docling_mcp.http_server

# Oppure con porta personalizzata
METRICS_PORT=9090 uv run python -m docling_mcp.http_server

{
  "status": "ok",
  "timestamp": 1732700400.123,
  "services": {
    "database": {
      "status": "up",
      "message": "PostgreSQL connection successful",
      "latency_ms": 5.2
    },
    "langfuse": {
      "status": "up",
      "message": "LangFuse client initialized",
      "latency_ms": 0.1
    },
    "embedder": {
      "status": "up",
      "message": "Embedder initialized and ready",
      "latency_ms": 0.5
    }
  }
}

# Verifica status DB index
uv run python scripts/verification/optimize_database.py --check

# Applica ottimizzazioni (upgrade HNSW index)
uv run python scripts/verification/optimize_database.py --apply

# Test performance
uv run python scripts/testing/test_mcp_performance.py

async with agent.run_stream(user_input, message_history=history) as result:
    async for text in result.stream_text(delta=False):
        print(f"\rAssistant: {text}", end="", flush=True)

SELECT c.content, d.title, d.source
FROM chunks c
JOIN documents d ON c.document_id = d.id
WHERE d.source ILIKE '%docling%'  -- Filtro applicato
ORDER BY c.embedding <=> query_embedding

# Avvia tutti i servizi
docker-compose up --build -d

# Visualizza i log
docker-compose logs -f rag-agent

# Default: CANCELLA il DB e reingerisce tutto (raccomandato)
docker-compose --profile ingestion up ingestion

# AGGIUNGERE documenti senza cancellare (può creare duplicati)
# Usa il doppio slash per Windows + Git Bash
docker-compose run --rm ingestion uv run python -m ingestion.ingest --documents //app/documents --no-clean

# Con opzioni personalizzate
docker-compose run --rm ingestion uv run python -m ingestion.ingest \
  --documents /app/documents \
  --chunk-size 800 \
  --verbose

# Ferma tutti i servizi
docker-compose down

# Ricostruisci le immagini dopo modifiche al codice
docker-compose build

# Visualizza i container attivi
docker-compose ps

# Accedi al container per debugging
docker-compose exec rag-agent bash

# Verifica connessione
psql $DATABASE_URL -c "SELECT 1"

# Verifica estensione PGVector
psql $DATABASE_URL -c "SELECT * FROM pg_extension WHERE extname = 'vector'"

# Test performance index
python scripts/verification/optimize_database.py --check

# Rimuovi cache e reinstalla
rm -rf .venv
uv sync

# Reset database (ATTENZIONE: cancella tutti i dati)
psql $DATABASE_URL < sql/optimize_index.sql

async def search_knowledge_base(
    ctx: RunContext[None],
    query: str,
    limit: int = 5,
    source_filter: str | None = None
) -> str:
    """
    Cerca nella knowledge base usando similarità semantica.

    Args:
        query: La query di ricerca per trovare informazioni rilevanti
        limit: Numero massimo di risultati da restituire (default: 5)
        source_filter: Filtro opzionale per cercare solo in fonti specifiche
                      Esempi: "docling", "langfuse-docs", "langfuse-docs/deployment"
                      Se fornito, verranno cercati solo documenti il cui percorso
                      sorgente contiene questa stringa

    Returns:
        Risultati di ricerca formattati con citazioni delle fonti
    """

# Cerca in tutta la knowledge base
await search_knowledge_base(query="come fare il deploy")

# Cerca solo nella documentazione Docling
await search_knowledge_base(
    query="come fare il deploy",
    source_filter="docling"
)

# Cerca solo nella sezione deployment di Langfuse
await search_knowledge_base(
    query="deployment cloud",
    source_filter="langfuse-docs/deployment"
)

-- Ricerca similarità vettoriale
SELECT * FROM match_chunks(
    query_embedding::vector(1536),
    match_count INT,
    similarity_threshold FLOAT DEFAULT 0.7
)

# Avvia il server di documentazione
uv run mkdocs serve

# Genera la documentazione in site/
uv run mkdocs build

docling-rag-agent/
├── app.py                         # Interfaccia web Streamlit
├── docling_mcp/                   # MCP server per Cursor IDE (standalone)
├── core/
│   ├── agent.py                   # PydanticAI agent wrapper
│   └── rag_service.py             # Core RAG logic (decoupled)
├── ingestion/
│   ├── ingest.py                  # Pipeline ingestione documenti
│   ├── embedder.py                # Generazione embedding con caching
│   └── chunker.py                 # Chunking intelligente (Docling HybridChunker)
├── utils/
│   ├── providers.py               # Configurazione modelli/client OpenAI
│   ├── db_utils.py                # Connection pooling ottimizzato
│   └── models.py                  # Modelli Pydantic per validazione
├── sql/
│   └── optimize_index.sql         # Schema completo + HNSW index ottimizzato
├── scripts/
│   ├── optimize_database.py       # Tool gestione index e performance
│   └── test_mcp_performance.py    # Performance test suite
├── docs/
│   ├── optimization-summary.md    # Analisi performance optimization
│   ├── performance-optimization-guide.md
│   └── optimization-deployment.md
├── documents/                     # Documenti per ingestione
├── pyproject.toml                 # Dipendenze progetto (uv)
├── .env.example                   # Template variabili d'ambiente
└── README.md                      # Questo file