rixdagen/README.md

# Riksdagen Sökplattform – Teknisk Översikt

En plattform för att utforska riksdagsdebatter och metadata. Backenden bygger på FastAPI, ArangoDB (med ArangoSearch), samt ChromaDB för vektorsök i chatten. Frontenden är en React/Vite-applikation skriven i TypeScript. LLM-funktionalitet kopplas in via `_llm`-paketet.

---

## 📋 Innehållsförteckning

1. [Systemöversikt](#systemöversikt)
2. [Projektstruktur](#projektstruktur)
3. [Backend-arkitektur](#backend-arkitektur)
4. [Frontend-arkitektur](#frontend-arkitektur)
5. [Dataflöden](#dataflöden)
6. [Viktiga Python- och TypeScript-komponenter](#viktiga-python--och-typescript-komponenter)
7. [ArangoDB och ArangoSearch](#arangodb-och-arangosearch)
8. [ChromaDB för vektorsök](#chromadb-för-vektorsök)
9. [LLM-integration](#llm-integration)
10. [Utvecklingsflöde](#utvecklingsflöde)
11. [Felsökning och tips](#felsökning-och-tips)

---

## 🏗️ Systemöversikt

```
┌─────────────┐    HTTP    ┌──────────────┐    Python    ┌───────────────┐
│   Browser   │ ─────────▶ │   FastAPI    │ ───────────▶ │   ArangoDB     │
│ (React)     │ ◀───────── │  backend     │ ◀─────────── │ (ArangoSearch) │
└─────────────┘            └──────┬───────┘              └───────────────┘
                                   │
                                   │ embeddings / metadata
                                   ▼
                           ┌──────────────┐
                           │   ChromaDB   │
                           └──────┬───────┘
                                   │
                                   ▼
                           ┌──────────────┐
                           │     _llm     │  (OpenAI API-kompatibel klient)
                           └──────────────┘
```

- **ArangoDB**: primär databas. Sök görs via ArangoSearch-vyer i stället för SQL.
- **ChromaDB**: håller embeddings för chatten och mer avancerad semantisk sökning.
- **LLM**: genererar chattsvar med hjälp av `_llm.LLM` (kopplad till t.ex. vLLM/OpenAI API).

---

## 📁 Projektstruktur

```
riksdagen/
├── arango_client.py           # Initierar Arango-klienten (används av backend & scripts)
├── backend/
│   ├── app.py                 # FastAPI-app, routerregistrering
│   ├── search.py              # SearchService med ArangoSearch-frågor
│   ├── chat.py                # Chat-endpoints (LLM + Chroma)
│   ├── vector.py              # Hjälpfunktioner för vektorsök (omfattar Chroma-anrop)
│   └── ...                    # Övriga routrar, scheman och konfigurationer
├── frontend/
│   ├── src/
│   │   ├── App.tsx            # Inträde, växlar mellan sök/chat-lägen
│   │   ├── api.ts             # Axios-klient mot `/api/*`
│   │   ├── types.ts           # TypeScript-typer för API-svar
│   │   ├── components/        # UI-komponenter (SearchPanel, ChatPanel m.fl.)
│   │   └── styles.css         # Globala stilar
│   └── vite.config.ts
├── scripts/
│   ├── ingest_arguments.py    # Exempel: läser in data till ArangoDB
│   └── build_embeddings.py    # Skapar embeddings och för in i Chroma
├── _arango/
│   ├── _arango.py             # Wrapper kring python-arango (förbättrad initiering)
│   ├── queries/               # Samling av AQL/ArangoSearch-frågor
│   └── helpers.py             # Hjälpfunktioner för AQL-byggande
├── _chromadb/
│   ├── client.py              # Instansierar ChromaDB-klient
│   ├── collections.py         # Hanterar samlingar (persistens, insättning, sök)
│   └── embeddings.py          # Hjälp för integrering mot embeddingsgenerator
├── _llm/
│   └── llm.py                 # LLM-wrapper (OpenAI API-kompatibelt gränssnitt)
└── README.md
```

> **Tips:** Utforska `_arango`, `_chromadb` och `_llm` för att förstå hur databaskopplingar och LLM-anrop är kapslade.

---

## 🔧 Backend-arkitektur

### `backend/app.py`

- Skapar FastAPI-instansen och exponerar endpoints under `/api`.
- Registrerar t.ex. `search_router`, `chat_router`, `meta_router`.
- Konfigurerar CORS så att frontenden kan nå backenden under utveckling och produktion.

### `backend/search.py`

- Innehåller klassen **`SearchService`**.
- `SearchService` använder `arango_client` och `_arango`-hjälpare för att köra ArangoSearch-frågor.
- Vanliga metoder (namn kan skilja något, läs filen för exakt signatur):
  - `search(...)`: bygger en ArangoSearch AQL-query med filter (parti, år, talare) samt scoring via `BM25()` eller `TFIDF()`.
  - `get_metadata(...)`: hämtar distinkta värden till frontendens filter.
  - `get_document_by_id(...)`: används för detaljerad visning/snippets.
- **Viktigt:** ingen SQL används. AQL byggs dynamiskt och exekveras mot en ArangoSearch-vy (se `_arango/queries`).

### `backend/chat.py`

- Hanterar endpointen `POST /api/chat`.
- Steg i chatthanteringen:
  1. Plockar senaste användarfrågan.
  2. Anropar ChromaDB (via `_chromadb`) för semantisk återhämtning.
  3. Kompletterar kontext med Arango-sökresultat om relevant.
  4. Bygger prompt och anropar `_llm.LLM`.
  5. Returnerar AI-svaret plus metadata (t.ex. vilka dokument som användes).
- Har ofta även `POST /api/vector-search` som låter frontenden testa Chroma-resultat separat.

### `backend/vector.py` (eller motsvarande modul)

- Innehåller hjälpfunktioner för att:
  - Normalisera text.
  - Skicka query till ChromaDB och hämta top-k embeddings-matchningar.
  - Eventuellt uppdatera/återskapa Chroma-samlingar.

---

## ⚛️ Frontend-arkitektur

- **`App.tsx`**: växlar mellan sök- och chat-läge (t.ex. via `const [mode, setMode] = useState<'search' | 'chat'>('search')`).
- **`api.ts`**: axios-klient som exporterar:
  - `searchTalks(params)` → `POST /api/search`.
  - `chat(messages, strategy)` → `POST /api/chat`.
  - `vectorSearch(query)` → `POST /api/vector-search`.
  - `getMeta()` → `GET /api/meta`.
- **`components/SearchPanel.tsx`**:
  - Kontrollerade inputs för fritext, år, parti m.m.
  - Använder `react-query` (`useMutation/useQuery`) för att trigga backend-anrop.
  - Visar resultat i `ResultsTable.tsx`.
- **`components/ChatPanel.tsx`**:
  - Håller konversation i state (lista av `{ role, content }`).
  - Skickar hela historiken till chat-endpointen.
  - Renderar streamen av svar.
- **`types.ts`**:
  - Speglar backendens Pydantic-scheman med TypeScript-interfaces (`SearchRequest`, `SearchResponse`, `TalkResult`, `ChatRequest`, etc.).
  - Bra översättning mellan Python-modeller och TypeScript.

---

## 🔄 Dataflöden

### Sökning via ArangoSearch

1. **Frontend** samlar filtervärden (t.ex. `query="skola"`, `party="S"`, `year=2023`).
2. `api.searchTalks` gör POST till `/api/search`.
3. **FastAPI** tar emot request → skapar `SearchService`.
4. `SearchService.search`:
   - Bygger AQL med `SEARCH`-klasuler mot en ArangoSearch-vy (exempel: `SEARCH ANALYZER(doc.anforande_text, "text_sv") LIKE "%skola%"`).
   - Använder `SORT BM25(doc)` eller `SORT doc.datum` beroende på begärda sorteringsparametrar.
   - Begränsar resultat (`LIMIT offset, limit`) och returnerar träffar + total count.
5. Backend serialiserar dokumenten till JSON (inklusive metadata som färger, snippet, etc.).
6. **Frontend** renderar resultat och uppdaterar paginering/statistikpaneler.

### Chatt med LLM

1. Användaren skriver fråga i chat-panelen.
2. `api.chat` skickar en lista av meddelanden (`[{ role: 'user', content: ... }, ...]`).
3. `backend/chat.py`:
   - Tar ut senaste användarfrågan.
   - `vector_search(...)` i samma modul eller via `_chromadb` hämtar semantiskt relevanta avsnitt.
   - Kan komplettera svar med `SearchService`-resultat för att säkerställa faktabas.
   - Lägger samman kontext och anropar `_llm.LLM`.
4. AI-svaret skickas tillbaka till frontenden och läggs på konversationen.

---

## 🧩 Viktiga Python- och TypeScript-komponenter

| Fil | Funktion |
|-----|----------|
| `arango_client.py` | Central Arango-klient. Återanvänds i backend och scripts. |
| `_arango/_arango.py` | Wrapper som läser miljövariabler, öppnar anslutningar och ger helpers för views/collections. |
| `_arango/queries/*` | Samlade AQL-snippets för sökning, metadata, detaljer. Läs dessa för att förstå exakta fält och filtreringslogik. |
| `_chromadb/client.py` | Skapar en Chroma-klient (kan vara persistent eller in-memory beroende på config). |
| `_chromadb/collections.py` | Hjälpfunktioner för att skapa/hämta Chroma-samlingar och göra `query`/`add`. |
| `_llm/llm.py` | LLM-wrapper. `LLM(model='vllm')` returnerar en klient med `.chat(messages=...)`. |
| `backend/search.py` | `SearchService` med AQL/ArangoSearch-hantering och responsformatering. |
| `backend/chat.py` | Chat-endpoints, orchestrerar Chroma + LLM + (valfritt) Arango-sök. |
| `frontend/src/api.ts` | Samlar alla HTTP-anrop till backend. Lätt att mocka i tester. |
| `frontend/src/components/*` | React-komponenter. Kommentera gärna i koden var data kommer ifrån och vad som skickas tillbaka till backend. |

---

## 🗄️ ArangoDB och ArangoSearch

- **Data** ligger i ArangoDB-kollektioner, ofta `talks`, `speakers`, `debates`, etc.
- **Views**: en ArangoSearch-vy (t.ex. `talks_view`) indexerar textfält med svenska analyser (`text_sv`). Detta gör att `SEARCH`-frågor kan använda ranking (BM25/TFIDF) och filtrera på fält.
- **AQL-byggstenar** (se `_arango/queries`):
  - `FOR doc IN talks_view`
  - `SEARCH ANALYZER(doc.anforande_text, "text_sv") LIKE "%..."%`
  - `FILTER doc.party == @party`
  - `SORT BM25(doc) DESC`
  - `LIMIT @offset, @limit`
- **Metadata**: Distinkta listor (ex. partier, år) hämtas via AQL `COLLECT`.

> **Ny i ArangoSearch?** Läs igenom `_arango/queries` och Arangos officiella exempel. Notera att ArangoSearch skiljer sig från vanliga AQL-index genom att all textindexering sker i vyn, inte kollektionen.

---

## 🧠 ChromaDB för vektorsök

- `_chromadb/client.py` konfigurerar anslutningen (lokal fil, DuckDB + Parquet som standard).
- Embeddings genereras i `scripts/build_embeddings.py`:
  1. Hämtar tal från ArangoDB med `arango_client`.
  2. Delar upp text i chunkar (se `_chromadb/embeddings.py` för heuristiken).
  3. Kör embeddingsgenerator (vanligen via `_llm` eller egen modul).
  4. Lagrar chunkar + metadata (`talk_id`, `speaker`, `party`, `source`) i Chroma-samlingen.

- Vid chat:
  - `vector_search` skickar användarfrågan som embedding till Chroma (`collection.query(query_texts=[...], n_results=top_k)`).
  - Resultatet innehåller `ids`, `documents`, `metadatas`, `distances` som matas in i prompten.

---

## 🤖 LLM-integration

- `_llm/llm.py` är huvudgränssnittet. Grundmönster:

  ```python
  from _llm import LLM

  def generate_answer(prompt: str) -> str:
      llm = LLM(model="vllm")
      messages = [
          {"role": "system", "content": "Du är en assistent som förklarar riksdagsdebatter sakligt."},
          {"role": "user", "content": prompt},
      ]
      response = llm.chat(messages=messages)
      return response
  ```

- Miljövariabler (`CHAT_MODEL`, `LLM_BASE_URL`, `LLM_API_KEY`) styr målmodell och endpoint.
- Chat-endpointen täcker redan vanlig användning. För experiment: återanvänd samma mönster men bygg tydlig prompt av kontexten du hämtar.

> Undvik onödiga `try/except`. Fel bubbla upp så att du ser den faktiska orsaken (t.ex. nätverksproblem, fel API-nyckel).

---

## 🛠️ Utvecklingsflöde

| Steg | Befallning | Kommentar |
|------|------------|-----------|
| Starta backend i utvecklingsläge | `uvicorn backend.app:app --reload --port 8000` | Körs i projektroten. Automatiskt reload vid filändring. |
| Starta frontend i dev-läge | `cd frontend && npm run dev` | Öppna http://localhost:5173 |
| Bygg frontend för produktion | `make frontend` | Skapar `frontend/dist`. |
| Ladda om nginx (om du serverar statiskt) | `sudo systemctl reload nginx` | Efter ny frontend-build. |
| Kör embeddings-script | `python -m scripts.build_embeddings --limit 500` | Uppdaterar Chroma-samlingen. |
| Kör anpassade Arango-script | `python -m scripts.ingest_arguments` | Exempel, kontrollera scriptens docstrings. |

---

## 🧪 Felsökning och tips

- **Arango-anslutning**: kör `python arango_client.py` för att testa att lösenord och URL stämmer.
- **Chroma-data**: öppna `_chromadb/client.py` och kontrollera `persist_directory`. Rensa katalogen om du behöver resetta.
- **Chat-svar saknar fakta**: kontrollera att `build_embeddings.py` har körts nyligen och att Chroma-samlingen innehåller rätt metadata.
- **React/TypeScript**:
  - Använd `useQuery` (för GET) och `useMutation` (för POST).
  - Håll komponenter små och bryt ut delkomponenter vid behov (t.ex. `FilterControls`, `ChatMessageList`).
  - Typsätt props, state och API-svar med `types.ts` för bättre editorstöd.
- **Python-stil**:
  - Lägg till type hints på funktioner (ex: `def search(self, params: SearchRequest) -> SearchResponse:`).
  - Skriv docstrings som beskriver syfte, parametrar och returvärden.
  - Undvik generella `try/except`; analysera felen vid körning och fixa orsaken.

---

## 🤔 Nästa steg

1. **Kommentera kod**: lägg till docstrings i `SearchService` och chat-hjälpare.
2. **Testa ArangoQueries**: skapa enhetstester som kör små AQL-scenarier med testdata.
3. **Frontend-guidning**: överväg inline-kommentarer i React-komponenterna för att förklara state-hantering.
4. **Observabilitet**: logga vilka ArangoSearch-queries som körs vid olika filterkombinationer.

---

## 📎 Referenser

- [ArangoDB Documentation – ArangoSearch](https://www.arangodb.com/docs/stable/arangosearch.html)
- [ChromaDB Python API](https://docs.trychroma.com/)
- [FastAPI – Depends och Pydantic](https://fastapi.tiangolo.com/)
- [React + TypeScript Cheatsheets](https://react-typescript-cheatsheet.netlify.app/)
- `batch_embed()` – Processar flera texter samtidigt

**Exempel**:
```python
def get_embedding(text: str, model: str = "embeddinggemma") -> List[float]:
    """
    Genererar en embedding-vektor för given text.
    
    Args:
        text: Texten att embedda
        model: Ollama-modell (default: embeddinggemma)
        
    Returns:
        Lista med floats (3072 dimensioner för embeddinggemma)
    """
    # Anropar http://192.168.1.11:11434/api/embeddings
    # Returnerar vektor
```

#### `backend/services/vector_store.py`

Hanterar pgvector-operationer:
- `create_embeddings_table()` – Skapar `talk_embeddings`-tabell
- `store_embedding()` – Sparar embedding i databas
- `query_similar_talks()` – Semantisk sökning

---

### Database: `backend/database.py`

**Viktigt**: Denna fil skapar databaskopplingen.

```python
# Skapar engine (kopplingen till PostgreSQL)
engine = create_engine(DATABASE_URL)

# Aktiverar pgvector-extension
with engine.connect() as conn:
    conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
    
# Session factory – används för att skapa databas-sessioner
SessionLocal = sessionmaker(bind=engine)

# Dependency för FastAPI – ger varje endpoint en databas-session
def get_db():
    db = SessionLocal()
    try:
        yield db  # Ger sessionen till endpointen
    finally:
        db.close()  # Stänger sessionen efter request
```

**Hur används det**:
```python
@router.post("/api/search")
def search_endpoint(request: SearchRequest, db: Session = Depends(get_db)):
    # db är nu en aktiv databas-session
    results = search_talks(db, ...)
```

---

## ⚛️ Frontend-arkitektur

### Huvudfil: `frontend/src/App.tsx`

Detta är root-komponenten som renderas i `index.html`.

```typescript
function App() {
  const [mode, setMode] = useState<'search' | 'chat' | 'vector'>('search');
  
  // mode styr vilket läge användaren är i:
  // - 'search': Vanlig nyckelordssökning
  // - 'chat': AI-chattläge
  // - 'vector': Semantisk vektorsökning
  
  return (
    <div>
      {/* Knappar för att växla läge */}
      <button onClick={() => setMode('search')}>Sök</button>
      <button onClick={() => setMode('chat')}>Chat</button>
      
      {/* Visar olika komponenter baserat på mode */}
      {mode === 'search' && <SearchPanel />}
      {mode === 'chat' && <ChatPanel />}
      {mode === 'vector' && <VectorSearchPanel />}
    </div>
  );
}
```

**Viktiga React-koncept**:
- `useState`: Skapar state-variabel som kan ändras. När `mode` ändras, re-renderar React komponenten.
- `{ }`: JavaScript-uttryck inuti JSX (React's HTML-liknande syntax)
- `&&`: Villkorlig rendering – `condition && <Component />` renderar bara om condition är true

---

### API-klient: `frontend/src/api.ts`

Detta är hur frontend pratar med backend.

```typescript
import axios from 'axios';

// Base URL – i produktion går detta via nginx reverse proxy
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api';

// axios-instans med konfigurerad base URL
const api = axios.create({
  baseURL: API_BASE_URL,
  headers: { 'Content-Type': 'application/json' }
});

// Funktion för att söka
export async function searchTalks(params: SearchParams): Promise<SearchResponse> {
  const response = await api.post('/search', params);
  return response.data;  // Backend returnerar JSON
}

// Funktion för att chatta
export async function chat(messages: ChatMessage[]): Promise<ChatResponse> {
  const response = await api.post('/chat', { messages });
  return response.data;
}
```

**TypeScript-koncept**:
- `async/await`: Hanterar asynkrona operationer (API-anrop)
- `Promise<T>`: Representerar ett framtida värde av typ T
- `interface`: Definierar shape av objekt (se `types.ts`)

---

### Komponenter

#### `frontend/src/components/SearchPanel.tsx`

Sökformulär med filter.

**State-hantering**:
```typescript
const [query, setQuery] = useState('');        // Fritextsök
const [party, setParty] = useState('');        // Valt parti
const [year, setYear] = useState<number | ''>('');  // Valt år
// ...fler filter

// react-query mutation för att söka
const searchMutation = useMutation({
  mutationFn: searchTalks,
  onSuccess: (data) => {
    // data innehåller SearchResponse från backend
    // Skickas till ResultsTable via props
  }
});

// När användaren klickar "Sök"
const handleSearch = () => {
  searchMutation.mutate({
    query,
    party,
    year,
    // ...andra filter
  });
};
```

**React Query (`useMutation`)**:
- Hanterar API-anrop automatiskt
- Ger tillgång till `isLoading`, `error`, `data`
- Cachas resultat för snabbare återanvändning

**JSX-exempel**:
```tsx
<input
  type="text"
  value={query}
  onChange={(e) => setQuery(e.target.value)}
  placeholder="Sök efter innehåll..."
/>
```

**Hur det fungerar**:
1. `value={query}` – Input-fältet visar värdet av `query` state
2. `onChange` – När användaren skriver, uppdateras `query` med `setQuery()`
3. Detta är "controlled component" pattern i React

---

#### `frontend/src/components/ResultsTable.tsx`

Visar sökresultat i tabell.

```typescript
interface ResultsTableProps {
  results: TalkResult[];  // Array av anföranden från backend
  total: int;             // Totalt antal träffar
  isLoading: boolean;     // Om data laddas
}

function ResultsTable({ results, total, isLoading }: ResultsTableProps) {
  if (isLoading) return <div>Laddar...</div>;
  
  if (results.length === 0) return <div>Inga resultat</div>;
  
  return (
    <table>
      <thead>
        <tr>
          <th>Datum</th>
          <th>Talare</th>
          <th>Parti</th>
          <th>Innehåll</th>
        </tr>
      </thead>
      <tbody>
        {results.map((talk) => (
          <tr key={talk.id}>
            <td>{talk.datum}</td>
            <td>{talk.talare}</td>
            <td style={{ color: talk.party_color }}>
              {talk.parti}
            </td>
            <td>{talk.snippet}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

**Viktigt**:
- `.map()`: Loopar över array och returnerar JSX för varje element
- `key={talk.id}`: React behöver unika keys för att effektivt uppdatera listan
- Props nedåt: Parent (SearchPanel) skickar data till child (ResultsTable)

---

#### `frontend/src/components/ChatPanel.tsx`

AI-chattgränssnitt.

**State**:
```typescript
const [messages, setMessages] = useState<ChatMessage[]>([
  { role: 'assistant', content: 'Hej! Vad vill du veta om riksdagsdebatter?' }
]);
const [input, setInput] = useState('');  // Användarens input

const chatMutation = useMutation({
  mutationFn: (msgs: ChatMessage[]) => chat(msgs),
  onSuccess: (response) => {
    // Lägg till AI-svaret i messages
    setMessages(prev => [...prev, { role: 'assistant', content: response.reply }]);
  }
});

const handleSend = () => {
  // Lägg till användarens meddelande
  const newMessages = [...messages, { role: 'user', content: input }];
  setMessages(newMessages);
  setInput('');  // Töm input-fält
  
  // Skicka till backend
  chatMutation.mutate(newMessages);
};
```

**Rendering**:
```tsx
<div className="chat-messages">
  {messages.map((msg, idx) => (
    <div key={idx} className={msg.role}>
      <strong>{msg.role === 'user' ? 'Du' : 'AI'}:</strong>
      <p>{msg.content}</p>
    </div>
  ))}
</div>

<input
  value={input}
  onChange={(e) => setInput(e.target.value)}
  onKeyPress={(e) => e.key === 'Enter' && handleSend()}
/>
<button onClick={handleSend}>Skicka</button>
```

---

#### `frontend/src/components/VectorSearchPanel.tsx`

Semantisk sökning via embeddings.

**Funktion**:
```typescript
const vectorMutation = useMutation({
  mutationFn: (query: string) => vectorSearch(query, 10),  // Top 10 resultat
  onSuccess: (data) => {
    // data.results innehåller liknande anföranden
  }
});

const handleVectorSearch = () => {
  vectorMutation.mutate(searchQuery);
};
```

Resultaten visas i samma format som `ResultsTable`.

---

### TypeScript-typer: `frontend/src/types.ts`

Definierar data-strukturer som matchar backend.

```typescript
// Matchar backend/schemas.py SearchRequest
export interface SearchParams {
  query: string;
  party?: string;
  year?: number;
  category?: string;
  speaker?: string;
  sort_by: string;
  sort_order: string;
  offset: number;
  limit: number;
}

// Matchar backend TalkResult
export interface TalkResult {
  id: string;
  datum: string;
  talare: string;
  parti: string;
  party_color: string;
  anforandetext: string;
  snippet: string;
  kategori?: string;
}

// Matchar backend SearchResponse
export interface SearchResponse {
  results: TalkResult[];
  total: number;
  offset: number;
  limit: number;
}
```

**Varför TypeScript?**
- Fångar fel vid compile-time (innan kod körs)
- Autocomplete i editorn
- Dokumenterar API:t automatiskt

---

## 🔄 Dataflöde

### Exempel: Användaren söker efter "skola"

1. **Frontend** (`SearchPanel.tsx`):
   ```typescript
   // Användaren skriver "skola" och klickar "Sök"
   handleSearch() {
     searchMutation.mutate({
       query: "skola",
       party: "",
       year: "",
       sort_by: "date",
       sort_order: "desc",
       offset: 0,
       limit: 50
     });
   }
   ```

2. **API-klient** (`api.ts`):
   ```typescript
   // axios skickar POST /api/search med JSON-body
   const response = await api.post('/search', params);
   ```

3. **nginx** (reverse proxy):
   ```
   location /api/ {
     proxy_pass http://127.0.0.1:8000/api/;
   }
   ```
   Omdirigerar till backend på port 8000.

4. **Backend** (`routes/search.py`):
   ```python
   @router.post("/api/search")
   def search_endpoint(request: SearchRequest, db: Session = Depends(get_db)):
       # Pydantic validerar request automatiskt
       results, total = search_talks(
           db=db,
           query=request.query,  # "skola"
           filters={
               "party": request.party,
               "year": request.year,
               # ...
           },
           sort_by=request.sort_by,
           sort_order=request.sort_order,
           offset=request.offset,
           limit=request.limit
       )
       
       return SearchResponse(
           results=results,
           total=total,
           offset=request.offset,
           limit=request.limit
       )
   ```

5. **Service** (`services/search_service.py`):
   ```python
   def search_talks(db, query, filters, ...):
       # Bygger SQL-fråga
       sql = f"""
           SELECT {', '.join(select_columns)}
           FROM talks
           WHERE anforandetext ILIKE %s
       """
       params = [f"%{query}%"]  # "%skola%"
       
       # Lägger till filter
       if filters.get('party'):
           sql += " AND parti = %s"
           params.append(filters['party'])
       
       # Kör fråga
       result = db.execute(text(sql), params)
       rows = result.fetchall()
       
       # Genererar snippets
       talks = [generate_snippet(row, query) for row in rows]
       
       return talks, len(talks)
   ```

6. **PostgreSQL**:
   ```sql
   SELECT id, datum, talare, parti, anforandetext, ...
   FROM talks
   WHERE anforandetext ILIKE '%skola%'
   ORDER BY datum DESC
   LIMIT 50 OFFSET 0;
   ```

7. **Backend** returnerar JSON:
   ```json
   {
     "results": [
       {
         "id": "abc123",
         "datum": "2023-11-15",
         "talare": "Anna Andersson",
         "parti": "S",
         "party_color": "#E8112d",
         "snippet": "...vi måste investera i <mark>skola</mark>n..."
       },
       ...
     ],
     "total": 234,
     "offset": 0,
     "limit": 50
   }
   ```

8. **Frontend** (`SearchPanel.tsx`):
   ```typescript
   onSuccess: (data) => {
     // react-query cachas svaret
     // ResultsTable uppdateras automatiskt med data.results
   }
   ```

9. **Rendering** (`ResultsTable.tsx`):
   ```tsx
   {results.map(talk => (
     <tr>
       <td>{talk.datum}</td>
       <td>{talk.talare}</td>
       <td style={{color: talk.party_color}}>{talk.parti}</td>
       <td dangerouslySetInnerHTML={{__html: talk.snippet}} />
     </tr>
   ))}
   ```

---

## 🗄️ Databas & Schema

### Huvudtabell: `talks`

**Kolumner** (definierat i `info.py` → `select_columns`):

```python
select_columns = [
    "id",                # Unikt ID (UUID)
    "datum",             # Datum (YYYY-MM-DD)
    "talare",            # Talarens namn
    "parti",             # Partikod (S, M, SD, etc.)
    "anforandetext",     # Fullständig text
    "kategori",          # Debattämne
    "year",              # År (extrakt från datum)
    "debatt_titel",      # Debattens titel
    "intressent_id",     # Talarens ID
    # ...fler kolumner
]
```

**Indexering** (viktigt för prestanda):

```sql
-- Trigram-index för fritextsökning
CREATE INDEX talks_text_trgm_idx ON talks USING gin(anforandetext gin_trgm_ops);

-- Index för filter
CREATE INDEX talks_year_idx ON talks(year);
CREATE INDEX talks_parti_idx ON talks(parti);
CREATE INDEX talks_datum_idx ON talks(datum);
```

---

### Embeddings-tabell: `talk_embeddings`

**Schema** (skapas i `services/vector_store.py`):

```sql
CREATE TABLE talk_embeddings (
    id SERIAL PRIMARY KEY,
    talk_id TEXT NOT NULL,           -- Referens till talks.id
    chunk_index INTEGER,             -- Vilken chunk (0, 1, 2, ...)
    chunk_text TEXT,                 -- Texten för chunken
    embedding vector(3072),          -- pgvector-kolumn (embeddinggemma = 3072 dim)
    metadata JSONB,                  -- Extra info (talare, parti, datum)
    created_at TIMESTAMP DEFAULT NOW()
);

-- Index för snabb vector-sökning
CREATE INDEX talk_embeddings_vector_idx ON talk_embeddings 
USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- Unique constraint för idempotens
CREATE UNIQUE INDEX talk_embeddings_unique_idx 
ON talk_embeddings(talk_id, chunk_index);
```

**Hur embeddings fungerar**:

1. Långt anförande delas upp i chunkar (~500 tokens vardera)
2. Varje chunk får en embedding-vektor (3072 floats)
3. Vektorn representerar semantisk mening
4. Vid sökning: Generera embedding för frågan, hitta närmaste chunkar via cosine similarity

**Exempel**:

```python
# Anförande från Anna Andersson (talk_id="abc123")
# Texten är 2000 ord → delas upp i 4 chunkar

talk_embeddings:
| id | talk_id | chunk_index | chunk_text          | embedding               | metadata                        |
|----|---------|-------------|---------------------|-------------------------|---------------------------------|
| 1  | abc123  | 0           | "Vi måste satsa..." | [0.23, -0.45, ...]      | {"talare": "Anna", "parti": "S"}|
| 2  | abc123  | 1           | "Skolan behöver..." | [0.12, -0.67, ...]      | {"talare": "Anna", "parti": "S"}|
| 3  | abc123  | 2           | "Lärare ska ha..."  | [-0.34, 0.89, ...]      | {"talare": "Anna", "parti": "S"}|
| 4  | abc123  | 3           | "Sammanfattning..." | [0.45, -0.12, ...]      | {"talare": "Anna", "parti": "S"}|
```

**Vector-sök SQL**:

```sql
-- Hitta de 5 mest liknande chunkarna till frågan "lärarutbildning"
SELECT 
    talk_id,
    chunk_text,
    metadata,
    embedding <=> :query_embedding AS distance  -- Cosine distance
FROM talk_embeddings
ORDER BY embedding <=> :query_embedding
LIMIT 5;
```

**Operator `<=>`**: pgvector's cosine distance operator (mindre värde = mer likt).

---

## 🤖 AI/LLM-funktionalitet

### LLM-wrapper: `_llm/llm.py`

**Vad den gör**: Abstraherar anrop till OpenAI-kompatibla API:er (t.ex. vLLM).

```python
from _llm import LLM

llm = LLM(model='vllm')  # eller 'gpt-4', 'gpt-3.5-turbo'

messages = [
    {"role": "system", "content": "Du är en AI som hjälper med riksdagsdebatter."},
    {"role": "user", "content": "Vad säger Socialdemokraterna om skatt?"}
]

response = llm.chat(messages=messages)
print(response)  # AI-genererat svar
```

**Konfiguration** (miljövariabler):

```bash
export LLM_BASE_URL=http://localhost:8000/v1  # vLLM server
export LLM_API_KEY=placeholder                # API-nyckel (om krävs)
export CHAT_MODEL=gpt-3.5-turbo               # Modell att använda
```

**Interna detaljer**:
- Använder `openai`-biblioteket under huven
- Hanterar streaming (om aktiverat)
- Kan konfigurera temperature, max_tokens, etc.

---

### Chat-flöde i backend

**Fil**: `backend/routes/chat.py`

```python
@router.post("/api/chat")
def chat_endpoint(request: ChatRequest, db: Session = Depends(get_db)):
    """
    AI-chat om riksdagsdebatter.
    
    Steg:
    1. Extrahera senaste användarfrågan
    2. Sök relevant kontext (vector eller keyword)
    3. Bygg prompt med systemmeddelande + kontext + fråga
    4. Anropa LLM
    5. Returnera svar
    """
    
    # Extrahera senaste frågan
    last_message = request.messages[-1]['content']
    
    # Sök kontext
    if request.strategy == 'vector':
        context = vector_search_for_chat(db, last_message)
    elif request.strategy == 'keyword':
        context = keyword_search(db, last_message)
    else:  # auto
        context = vector_search_for_chat(db, last_message)
        if not context:
            context = keyword_search(db, last_message)
    
    # Bygg prompt
    system_message = {
        "role": "system",
        "content": f"""Du är en AI-assistent som hjälper användare att förstå 
                      svenska riksdagsdebatter. 
                      
                      Här är relevant information från debatterna:
                      {context}
                      
                      Svara koncist baserat på denna information."""
    }
    
    messages = [system_message] + request.messages
    
    # Anropa LLM
    llm = LLM(model='vllm')
    response = llm.chat(messages=messages)
    
    return {"reply": response, "context_used": len(context)}
```

---

### Embeddings-generering

**Fil**: `scripts/build_embeddings.py`

**Vad scriptet gör**:
1. Hämtar anföranden från `talks`-tabellen (batchvis med `LIMIT` och `OFFSET`)
2. Delar upp varje anförande i chunkar
3. Genererar embeddings via Ollama
4. Sparar i `talk_embeddings` med `ON CONFLICT DO NOTHING` (idempotent)

**Körning**:
```bash
# Processa första 200 anföranden
python -m scripts.build_embeddings --limit 200

# Fortsätt från rad 200
python -m scripts.build_embeddings --limit 200 --offset 200

# Processa alla (varning: kan ta timmar!)
python -m scripts.build_embeddings --limit 1000000
```

**Viktiga funktioner**:

```python
def process_talk(talk: dict, db: Session):
    """
    Processar ett enda anförande.
    
    Args:
        talk: Dict med talk-data (id, anforandetext, talare, etc.)
        db: Databas-session
    """
    # Chunka texten
    chunks = chunk_text(talk['anforandetext'], max_tokens=500)
    
    # För varje chunk
    for idx, chunk in enumerate(chunks):
        # Generera embedding
        embedding = get_embedding(chunk)
        
        # Spara till databas
        store_embedding(
            db=db,
            talk_id=talk['id'],
            chunk_index=idx,
            chunk_text=chunk,
            embedding=embedding,
            metadata={
                "talare": talk['talare'],
                "parti": talk['parti'],
                "datum": talk['datum']
            }
        )
```

**Progress-tracking**:
```
Processar anföranden 0-200...
[█████████░░░░░░░░░░░] 47% (94/200) - ETA: 2m 34s
```

---

## 🔧 Utvecklingsflöde

### Starta utvecklingsmiljö

#### 1. Backend
```bash
# Terminal 1
cd /home/lasse/riksdagen
uvicorn backend.app:app --reload --port 8000

# --reload: Startar om automatiskt vid kodändring
# --port 8000: Lyssnar på port 8000
```

**Verifiera**: Gå till `http://localhost:8000/docs` (FastAPI Swagger UI)

#### 2. Frontend (utvecklingsläge)
```bash
# Terminal 2
cd /home/lasse/riksdagen/frontend
npm run dev

# Startar Vite dev-server på http://localhost:5173
# Hot module replacement (HMR) aktiverat
```

#### 3. Bygg för produktion
```bash
# Från projektroten
make frontend

# Eller manuellt
cd frontend
npm install    # Installera dependencies
npm run build  # Bygger till frontend/dist/

# Ladda om nginx
sudo systemctl reload nginx
```

---

### Vanliga ändringsscenarier

#### Scenario 1: Lägg till ny filter-parameter

**Backend** (`backend/schemas.py`):
```python
class SearchRequest(BaseModel):
    # ...existing fields...
    municipality: Optional[str] = None  # Ny parameter
```

**Backend** (`services/search_service.py`):
```python
def search_talks(db, query, filters, ...):
    # ...existing code...
    
    if filters.get('municipality'):
        sql += " AND municipality = %s"
        params.append(filters['municipality'])
```

**Frontend** (`types.ts`):
```typescript
export interface SearchParams {
  // ...existing fields...
  municipality?: string;  // Ny parameter
}
```

**Frontend** (`SearchPanel.tsx`):
```tsx
const [municipality, setMunicipality] = useState('');

// I JSX
<select value={municipality} onChange={(e) => setMunicipality(e.target.value)}>
  <option value="">Alla kommuner</option>
  <option value="Stockholm">Stockholm</option>
  {/* ...fler alternativ */}
</select>

// I handleSearch
searchMutation.mutate({
  // ...existing params...
  municipality
});
```

**Efter ändringar**:
1. Starta om backend (Ctrl+C, kör uvicorn igen)
2. Frontend uppdateras automatiskt (Vite HMR)

---

#### Scenario 2: Lägg till ny endpoint

**Backend** (`backend/routes/stats.py` – ny fil):
```python
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from backend.database import get_db

router = APIRouter(prefix="/api", tags=["statistics"])

@router.get("/stats/party-distribution")
def get_party_distribution(db: Session = Depends(get_db)):
    """
    Returnerar antal anföranden per parti.
    """
    result = db.execute(text("""
        SELECT parti, COUNT(*) as count
        FROM talks
        GROUP BY parti
        ORDER BY count DESC
    """))
    
    return [{"party": row[0], "count": row[1]} for row in result]
```

**Backend** (`backend/app.py`):
```python
# ...existing imports...
from backend.routes.stats import router as stats_router

# ...existing code...
app.include_router(stats_router)
```

**Frontend** (`api.ts`):
```typescript
export async function getPartyDistribution(): Promise<PartyDistribution[]> {
  const response = await api.get('/stats/party-distribution');
  return response.data;
}
```

**Frontend** (ny komponent `StatsPanel.tsx`):
```typescript
import { useQuery } from '@tanstack/react-query';
import { getPartyDistribution } from '../api';

function StatsPanel() {
  const { data, isLoading } = useQuery({
    queryKey: ['party-distribution'],
    queryFn: getPartyDistribution
  });
  
  if (isLoading) return <div>Laddar...</div>;
  
  return (
    <div>
      <h2>Anföranden per parti</h2>
      <ul>
        {data?.map(item => (
          <li key={item.party}>
            {item.party}: {item.count}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

---

#### Scenario 3: Ändra databas-schema

**1. Manuell ändring** (för utveckling):
```sql
-- Koppla till PostgreSQL
psql -U riksdagen -d riksdagen

-- Lägg till kolumn
ALTER TABLE talks ADD COLUMN sentiment VARCHAR(20);

-- Uppdatera info.py
# Lägg till "sentiment" i select_columns
```

**2. För produktion: Använd migreringsverktyg (Alembic)**

```bash
# Installera Alembic
pip install alembic

# Initiera
alembic init alembic

# Skapa migration
alembic revision -m "Add sentiment column"

# Redigera filen i alembic/versions/
def upgrade():
    op.add_column('talks', sa.Column('sentiment', sa.String(20)))

def downgrade():
    op.drop_column('talks', 'sentiment')

# Kör migration
alembic upgrade head
```

---

## 🐛 Felsökning

### Problem: Frontend visar 502 Bad Gateway

**Orsak**: nginx kan inte nå backend.

**Lösning**:
```bash
# 1. Kolla att backend körs
curl http://127.0.0.1:8000/healthz

# Om inget svar:
uvicorn backend.app:app --reload --port 8000

# 2. Kolla nginx-konfiguration
sudo nginx -t

# 3. Kolla nginx-loggar
sudo tail -f /var/log/nginx/error.log
```

---

### Problem: TypeScript-fel i frontend

**Fel**: `Property 'X' does not exist on type 'Y'`

**Orsak**: Type mismatch mellan frontend och backend.

**Lösning**:
1. Kolla backend-schema i `backend/schemas.py`
2. Uppdatera motsvarande interface i `frontend/src/types.ts`
3. Kör `npm run build` för att verifiera

---

### Problem: Inget resultat från vector-sök

**Orsak**: Inga embeddings genererade.

**Lösning**:
```bash
# 1. Kolla att tabellen finns
psql -U riksdagen -d riksdagen -c "SELECT COUNT(*) FROM talk_embeddings;"

# Om 0 rader:
python -m scripts.build_embeddings --limit 100

# 2. Kolla att Ollama körs
curl http://192.168.1.11:11434/api/tags

# 3. Testa embedding-generering
python -c "
from backend.services.embedding import get_embedding
emb = get_embedding('test')
print(len(emb))  # Ska ge 3072
"
```

---

### Problem: Chat-svar är irrelevanta

**Orsak**: Dålig kontext från sök.

**Debug**:
```python
# I backend/routes/chat.py, lägg till logging
import logging
logger = logging.getLogger(__name__)

# I chat_endpoint
logger.info(f"Context found: {len(context)} characters")
logger.info(f"First 200 chars: {context[:200]}")

# Kör backend med log-level DEBUG
uvicorn backend.app:app --reload --log-level debug
```

**Lösning**:
1. Öka `top_k` i vector-sök (fler resultat)
2. Förbättra chunkning-strategi (överlappande chunkar)
3. Justera prompt i system-message

---

### Problem: Långsam sökning

**Orsak**: Saknade index.

**Lösning**:
```sql
-- Kolla existerande index
SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'talks';

-- Lägg till saknade index
CREATE INDEX talks_text_trgm_idx ON talks USING gin(anforandetext gin_trgm_ops);
CREATE INDEX talks_year_idx ON talks(year);
CREATE INDEX talks_parti_idx ON talks(parti);

-- För vector-sök
CREATE INDEX talk_embeddings_vector_idx ON talk_embeddings 
USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
```

**Optimering**:
```python
# I services/search_service.py
# Begränsa kolumner som returneras
select_columns = ["id", "datum", "talare", "parti", "snippet"]  # Inte hela anforandetext

# Använd paginering
LIMIT 50 OFFSET 0  # Hämta bara 50 rader åt gången
```

---

## 📝 Sammanfattning: Viktiga filer och deras roller

| Fil | Vad den gör |
|-----|-------------|
| `backend/app.py` | Root för FastAPI-app, registrerar alla routes |
| `backend/database.py` | Databaskoppling, session-factory, aktiverar pgvector |
| `backend/routes/search.py` | Endpoint för nyckelordssökning |
| `backend/routes/chat.py` | Endpoints för AI-chat och vector-sök |
| `backend/services/search_service.py` | SQL-frågor för sökning, snippet-generering |
| `backend/services/vector_store.py` | pgvector-operationer, likhetssökning |
| `backend/services/embedding.py` | Chunkning, embedding-generering via Ollama |
| `frontend/src/App.tsx` | Root-komponent, mode-switching (sök/chat/vector) |
| `frontend/src/api.ts` | Axios-baserad API-klient |
| `frontend/src/components/SearchPanel.tsx` | Sökformulär med filter |
| `frontend/src/components/ChatPanel.tsx` | Chat-gränssnitt |
| `frontend/src/components/ResultsTable.tsx` | Tabellvisning av resultat |
| `scripts/build_embeddings.py` | Genererar embeddings för alla anföranden |
| `_llm/llm.py` | Wrapper för OpenAI-kompatibla LLM-anrop |
| `info.py` | Konstanter (partier, färger, kolumner) |
| `config.py` | Databas-URL och konfiguration |

---

## 🚀 Nästa steg: Förslag på förbättringar

1. **Streaming för chat**: Visa AI-svaret ord för ord (WebSocket eller Server-Sent Events)
2. **Caching**: Spara frekventa frågor i Redis för snabbare svar
3. **Feedback-loop**: Använd användarfeedback för att förbättra sökresultat
4. **Avancerad filtrering**: Datum-intervall, flera partier samtidigt
5. **Export-funktion**: Ladda ner resultat som CSV/PDF
6. **Visualiseringar**: Diagram för partier, tidslinjer, sentiment-analys

---

## 🆘 Hjälp och support

- **Backend-loggar**: `uvicorn backend.app:app --log-level debug`
- **Frontend-konsol**: Öppna DevTools (F12) i webbläsaren
- **Databas-frågor**: `psql -U riksdagen -d riksdagen`
- **API-dokumentation**: `http://localhost:8000/docs` (när backend körs)

Lycka till med utvecklingen! 🎉