breakpilot-compliance/developer-portal/app/api/rag/page.tsx

import { DevPortalLayout, ApiEndpoint, CodeBlock, ParameterTable, InfoBox } from '@/components/DevPortalLayout'

export default function RAGApiPage() {
  return (
    <DevPortalLayout
      title="RAG API"
      description="Semantische Suche im Legal Corpus (DSGVO, AI Act, NIS2)"
    >
      <h2>Uebersicht</h2>
      <p>
        Die RAG (Retrieval-Augmented Generation) API ermoeglicht semantische Suche
        im Compliance-Korpus. Der Korpus enthaelt:
      </p>
      <ul>
        <li>DSGVO (Datenschutz-Grundverordnung)</li>
        <li>AI Act (EU KI-Verordnung)</li>
        <li>NIS2 (Netzwerk- und Informationssicherheit)</li>
        <li>ePrivacy-Verordnung</li>
        <li>Bundesdatenschutzgesetz (BDSG)</li>
      </ul>

      <InfoBox type="info" title="Embedding-Modell">
        Die Suche verwendet BGE-M3 Embeddings fuer praezise semantische Aehnlichkeit.
        Die Vektoren werden in Qdrant gespeichert.
      </InfoBox>

      <h2>GET /rag/search</h2>
      <p>Durchsucht den Legal Corpus semantisch.</p>

      <h3>Query-Parameter</h3>
      <ParameterTable
        parameters={[
          {
            name: 'q',
            type: 'string',
            required: true,
            description: 'Die Suchanfrage (z.B. "Einwilligung personenbezogene Daten")',
          },
          {
            name: 'top_k',
            type: 'number',
            required: false,
            description: 'Anzahl der Ergebnisse (default: 5, max: 20)',
          },
          {
            name: 'corpus',
            type: 'string',
            required: false,
            description: 'Einschraenkung auf bestimmten Corpus: dsgvo, ai_act, nis2, all (default: all)',
          },
          {
            name: 'min_score',
            type: 'number',
            required: false,
            description: 'Minimaler Relevanz-Score 0-1 (default: 0.5)',
          },
        ]}
      />

      <h3>Request</h3>
      <CodeBlock language="bash" filename="cURL">
{`curl -X GET "https://api.breakpilot.io/sdk/v1/rag/search?q=Einwilligung%20DSGVO&top_k=5" \\
  -H "Authorization: Bearer YOUR_API_KEY"`}
      </CodeBlock>

      <h3>Response (200 OK)</h3>
      <CodeBlock language="json" filename="Response">
{`{
  "success": true,
  "data": {
    "query": "Einwilligung DSGVO",
    "results": [
      {
        "id": "dsgvo-art-7",
        "title": "Art. 7 DSGVO - Bedingungen fuer die Einwilligung",
        "content": "Beruht die Verarbeitung auf einer Einwilligung, muss der Verantwortliche nachweisen koennen, dass die betroffene Person in die Verarbeitung ihrer personenbezogenen Daten eingewilligt hat...",
        "corpus": "dsgvo",
        "article": "Art. 7",
        "score": 0.92,
        "metadata": {
          "chapter": "II",
          "section": "Einwilligung",
          "url": "https://dsgvo-gesetz.de/art-7-dsgvo/"
        }
      },
      {
        "id": "dsgvo-art-6-1-a",
        "title": "Art. 6 Abs. 1 lit. a DSGVO - Einwilligung als Rechtsgrundlage",
        "content": "Die Verarbeitung ist nur rechtmaessig, wenn mindestens eine der nachstehenden Bedingungen erfuellt ist: a) Die betroffene Person hat ihre Einwilligung...",
        "corpus": "dsgvo",
        "article": "Art. 6",
        "score": 0.88,
        "metadata": {
          "chapter": "II",
          "section": "Rechtmaessigkeit",
          "url": "https://dsgvo-gesetz.de/art-6-dsgvo/"
        }
      }
    ],
    "total_results": 2,
    "search_time_ms": 45
  },
  "meta": {
    "corpus_version": "2026-01",
    "embedding_model": "bge-m3"
  }
}`}
      </CodeBlock>

      <h2>GET /rag/status</h2>
      <p>Gibt Status-Informationen ueber das RAG-System zurueck.</p>

      <h3>Request</h3>
      <CodeBlock language="bash" filename="cURL">
{`curl -X GET "https://api.breakpilot.io/sdk/v1/rag/status" \\
  -H "Authorization: Bearer YOUR_API_KEY"`}
      </CodeBlock>

      <h3>Response (200 OK)</h3>
      <CodeBlock language="json" filename="Response">
{`{
  "success": true,
  "data": {
    "status": "healthy",
    "corpus": {
      "dsgvo": {
        "documents": 99,
        "chunks": 1250,
        "last_updated": "2026-01-15T00:00:00Z"
      },
      "ai_act": {
        "documents": 89,
        "chunks": 980,
        "last_updated": "2026-01-20T00:00:00Z"
      },
      "nis2": {
        "documents": 46,
        "chunks": 520,
        "last_updated": "2026-01-10T00:00:00Z"
      }
    },
    "embedding_service": {
      "status": "online",
      "model": "bge-m3",
      "dimension": 1024
    },
    "vector_db": {
      "type": "qdrant",
      "collections": 3,
      "total_vectors": 2750
    }
  }
}`}
      </CodeBlock>

      <h2>SDK Integration</h2>
      <p>
        Verwenden Sie den SDK-Client fuer einfache RAG-Suche:
      </p>
      <CodeBlock language="typescript" filename="rag-search.ts">
{`import { getSDKBackendClient, isLegalQuery } from '@breakpilot/compliance-sdk'

const client = getSDKBackendClient()

// Pruefen ob die Query rechtliche Inhalte betrifft
if (isLegalQuery('Was ist eine Einwilligung?')) {
  // RAG-Suche durchfuehren
  const results = await client.search('Einwilligung DSGVO', 5)

  results.forEach(result => {
    console.log(\`[\${result.corpus}] \${result.title}\`)
    console.log(\`Score: \${result.score}\`)
    console.log(\`URL: \${result.metadata.url}\`)
    console.log('---')
  })
}`}
      </CodeBlock>

      <h2>Keyword-Erkennung</h2>
      <p>
        Die Funktion <code>isLegalQuery</code> erkennt automatisch rechtliche Anfragen:
      </p>
      <CodeBlock language="typescript" filename="keyword-detection.ts">
{`import { isLegalQuery } from '@breakpilot/compliance-sdk'

// Gibt true zurueck fuer:
isLegalQuery('DSGVO Art. 5')        // true - Artikel-Referenz
isLegalQuery('Einwilligung')        // true - DSGVO-Begriff
isLegalQuery('AI Act Hochrisiko')   // true - AI Act Begriff
isLegalQuery('NIS2 Richtlinie')     // true - NIS2 Referenz
isLegalQuery('personenbezogene Daten') // true - Datenschutz-Begriff

// Gibt false zurueck fuer:
isLegalQuery('Wie ist das Wetter?') // false - Keine rechtliche Anfrage
isLegalQuery('Programmiere mir X')  // false - Technische Anfrage`}
      </CodeBlock>

      <h2>Beispiel: Command Bar Integration</h2>
      <CodeBlock language="typescript" filename="command-bar-rag.tsx">
{`import { useState } from 'react'
import { getSDKBackendClient, isLegalQuery } from '@breakpilot/compliance-sdk'

function CommandBarSearch({ query }: { query: string }) {
  const [results, setResults] = useState([])
  const [loading, setLoading] = useState(false)

  useEffect(() => {
    if (query.length > 3 && isLegalQuery(query)) {
      setLoading(true)
      const client = getSDKBackendClient()

      client.search(query, 3).then(data => {
        setResults(data)
        setLoading(false)
      })
    }
  }, [query])

  if (!isLegalQuery(query)) return null

  return (
    <div className="rag-results">
      {loading ? (
        <p>Suche im Legal Corpus...</p>
      ) : (
        results.map(result => (
          <div key={result.id} className="result-card">
            <h4>{result.title}</h4>
            <p>{result.content.slice(0, 200)}...</p>
            <a href={result.metadata.url} target="_blank">
              Volltext lesen
            </a>
          </div>
        ))
      )}
    </div>
  )
}`}
      </CodeBlock>

      <InfoBox type="warning" title="Rate Limits">
        Die RAG-Suche ist auf 100 Anfragen/Minute (Professional) bzw.
        unbegrenzt (Enterprise) limitiert. Implementieren Sie Client-Side
        Debouncing fuer Echtzeit-Suche.
      </InfoBox>
    </DevPortalLayout>
  )
}