7dayrag

Produktionsorientierter RAG- und KI-Agenten-Workflow, der als FastAPI-Dienst bereitgestellt wird. Entwickelt als Referenzimplementierung für ein 7-tägiges SaaS-KI-Engagement – fundierte Q&A über Geschäftsdaten mit Zitaten, Verweigerungs-Schutzmechanismen und einem Tool-nutzenden Agenten, der interne APIs aufruft.

Siehe ARCHITECTURE.md für die Design-Begründung und den Tagesplan für die Lieferung.

Schnellstart (keine API-Schlüssel erforderlich)

Die App läuft vollständig offline im Stub-Modus (deterministische Pseudo-Embeddings + skriptbasiertes LLM). Fügen Sie später echte Schlüssel hinzu, um mit automatischem Failover auf OpenAI/Anthropic umzuschalten.

# 1. Postgres + pgvector
docker compose up -d db

# 2. Python deps
pip install -r requirements.txt

# 3. Configure (or skip: defaults match compose)
copy .env.example .env

# 4. Create schema + load the sample knowledge base
python -m scripts.seed_sample_data

# 5. Serve
uvicorn app.main:app --port 8000 --reload

Ausprobieren

# Grounded Q&A with citations
curl -X POST localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the uptime SLA for Business plans?"}'

# Agent that calls tools (ticket lookup)
curl -X POST localhost:8000/api/v1/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Check ticket TICKET-1001 and summarize its status."}'

# Raw hybrid retrieval (debug/tuning)
curl -X POST localhost:8000/api/v1/documents/search \
  -H "Content-Type: application/json" \
  -d '{"query": "refund window annual plan", "top_n": 3}'

Interaktive Dokumentation: http://localhost:8000/docs

API

Jede Antwort enthält eine x-request-id; Fehler sind strukturiert als {error: {code, message}}.

Konfiguration

Alles über Umgebung / .env (siehe .env.example). Wichtige Einstellungen:

• LLM_PROVIDER: openai | anthropic | stub | auto (auto durchläuft PROVIDER_ORDER mit Wiederholungsversuchen pro Anbieter + Backoff und Failover; endet bei stub, wenn keine Schlüssel gesetzt sind)

• OPENAI_BASE_URL: auf einen beliebigen OpenAI-kompatiblen Endpunkt zeigen (Ollama, vLLM, Gateways)

• MIN_VECTOR_SCORE: Untergrenze für den besten Kosinus-Treffer, unterhalb derer die API verweigert statt zu raten

• TICKETS_API_BASE_URL / ACCOUNTS_API_BASE_URL: Agent-Tools auf echte interne APIs richten; leer = eingebaute Sandbox-Daten

• REDIS_URL, CACHE_ENABLED, CACHE_TTL_SECONDS, RATE_LIMIT_PER_MINUTE: Caching + Ratenbegrenzung; ein fehlendes Redis kostet nur Leistung, nie Verfügbarkeit

Redis (Caching + Ratenbegrenzung)

Fundierte Antworten werden zwischengespeichert (nach Frage + Konfiguration) und /api/v1/* ist pro Client-IP mit einem festen 60-Sekunden-Fenster ratenbegrenzt. Antworten enthalten x-ratelimit-remaining; das Überschreiten des Limits gibt strukturiertes 429 zurück. /readyz meldet den Redis-Status; die API fällt offen aus, wenn Redis nicht verfügbar ist. Nur Nicht-Verweigerungs-Antworten werden zwischengespeichert (Verweigerungen können sich ändern, wenn Dokumente aktualisiert werden).

docker compose up -d redis   # or just: docker compose up -d  (brings up db+redis+api+n8n)

MCP-Server

Stellen Sie dieselben Fähigkeiten für Claude Desktop oder jeden MCP-Client bereit:

python mcp_server.py        # stdio transport

Tools: search_knowledge_base, answer_question, run_agent, lookup_ticket, lookup_account. Claude-Desktop-Konfigurationsausschnitt:

{
  "mcpServers": {
    "7dayrag": {
      "command": "python",
      "args": ["/absolute/path/to/7dayrag/mcp_server.py"]
    }
  }
}

n8n-Workflow-Automatisierung

docker compose up -d n8n → öffnen Sie http://localhost:5678 → importieren Sie aus workflows/:

Workflows rufen http://api:8000 auf (Compose-Netzwerk). Wenn Sie n8n außerhalb von Compose ausführen, ändern Sie die Basis-URL auf http://localhost:8000.

Testen Sie den Triage-Webhook nach der Aktivierung:

curl -X POST localhost:5678/webhook/ticket-triage \
  -H "Content-Type: application/json" -d '{"ticket_id": "TICKET-1001"}'

So funktioniert die Fundierung

1. Die Frage wird eingebettet (gleiches Modell wie bei der Aufnahme) und durch hybride Abfrage geführt: pgvector-Kosinus-Top-K + Postgres-Volltext-Top-K, fusioniert mit Reciprocal Rank Fusion.

2. Wenn der Vektor-Score des besten Treffers unter MIN_VECTOR_SCORE liegt → Verweigerung (kein LLM-Aufruf).

3. Andernfalls geht der nummerierte Kontext mit strengen Regeln an das Modell: als [n] zitieren, nur aus dem Kontext antworten, andernfalls NOT_ENOUGH_CONTEXT antworten.

4. Zitate in der Antwort werden auf Quelldokumente zurückgeführt und zurückgegeben.

Tests

docker compose up -d db      # integration tests need Postgres on :5433
pytest tests -q              # unit + integration; integration skips cleanly without DB
ruff check app tests scripts

21 Tests: Chunking-Invarianten, RRF-Fusion, Embedding-Determinismus, Stub-Provider-Verhalten, Agenten-Schleifen-Parsing, plus End-to-End-API-Roundtrips gegen echte Postgres/pgvector.

Bereitstellung (Staging)

cp .env.example .env   # add OPENAI_API_KEY
docker compose up -d --build
curl localhost:8000/readyz
curl -X POST localhost:8000/api/v1/admin/seed

Für AWS: gleiche Images → ECS Fargate + RDS Postgres (aktivieren Sie die pgvector-Erweiterung). Für DigitalOcean: Droplet + verwaltetes Postgres. Geheimnisse nur über Umgebung/Secret-Manager.

Projektstruktur

app/
  api/        FastAPI routes (documents, query, agent, health/admin)
  agent/      tool registry (KB search, ticket/account lookup) + bounded agent loop
  llm/        provider abstraction: openai, anthropic, stub + retry/failover router
  rag/        chunking, ingestion, hybrid retrieval (RRF), grounded generation
  cache.py    Redis: response cache + fixed-window rate limiting (fail-open)
  config.py   env-driven settings · db.py engine/session · db_init.py schema bootstrap
data/sample_docs/*.md    demo knowledge base
scripts/seed_sample_data.py
workflows/*.json         importable n8n automations (ticket triage, KB sync)
mcp_server.py            MCP tool server (stdio) for Claude Desktop / MCP clients
tests/

Nächste Schritte (Backlog nach dem Engagement)

Streaming (SSE), Feedback-Erfassung in ein Evaluierungsset, Reranker-Stufe, Multi-Tenant-RLS, geplante Neuindizierung, Prompt-Versionierung/A-B, Kosten-Dashboards.