# 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 och AQL; inga relationsfrågor används.
- **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.

### `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 (`SearchPanel.tsx`)** samlar användarens filter och anropar `searchTalks` i `frontend/src/api.ts`.
2. **FastAPI (`backend/search.py`)** tar emot POST `/api/search`, instansierar `SearchService` och skickar vidare parametrar.
3. **`SearchService.search`** bygger en AQL-fråga mot ArangoSearch-vyn (t.ex. `talks_view`) där filter och scoring läggs till. Se `_arango/queries/search_view.py` för den faktiska queryn.
   ```aql
   FOR doc IN talks_view
     SEARCH ANALYZER(doc.anforande_text, "text_sv") %PHRASE(@query)% 
     FILTER (@party == null OR doc.party == @party)
     FILTER (@year  == null OR doc.year  == @year)
     SORT BM25(doc) DESC
     LIMIT @offset, @limit
     RETURN MERGE(doc, { snippet: doc.preview })
   ```
4. **ArangoDB** returnerar matchande dokument. Backend formaterar svaren (färger, snippet) och skickar JSON tillbaka.
5. **Frontend** renderar resultatet i `ResultsTable.tsx`, uppdaterar statistikpaneler och hanterar paginering.

### Chattflöde med LLM och Chroma

1. **Frontend (`ChatPanel.tsx`)** skickar konversationen till `POST /api/chat`.
2. **`backend/chat.py`**:
   - Extraherar senaste användarfrågan.
   - Hämtar relevanta chunkar via Chroma (`_chromadb.collections.get_collection(...).query(...)`).
   - Optionellt kompletterar kontexten med `SearchService.search` för ArangoSearch-träffar.
   - Bygger prompten, anropar `_llm.LLM(model="vllm")` och returnerar svaret.
3. **Frontend** lägger till AI-svaret i konversationen och visar källor/metadata för transparens.

---

## 🧩 Viktiga Python- och TypeScript-komponenter

| Fil | Funktion |
|-----|----------|
| `arango_client.py` | Initierar Arango-klienten med anslutningsuppgifter från miljön. |
| `_arango/_arango.py` | Wrapper som kapslar uppkoppling och hjälpfunktioner mot ArangoDB och views. |
| `_arango/queries/*` | Samling återskapbara AQL-snippets för sök, metadata och detaljhämtning. |
| `_chromadb/client.py` | Skapar ChromaDB-klienten (lokal DuckDB + Parquet som standard). |
| `_chromadb/collections.py` | Hjälper till att skapa/hämta Chroma-samlingar, lägga in chunkar och göra `query`. |
| `_llm/llm.py` | OpenAI-kompatibel klient. Använd `LLM(model='vllm')` och `chat(...)` för generering. |
| `backend/search.py` | Innehåller `SearchService` och API-routes för sök, bygger AQL mot ArangoSearch. |
| `backend/chat.py` | Chat- och vector-endpoints. Kopplar ihop Chroma-resultat med LLM-svar. |
| `frontend/src/api.ts` | Axios-klient för att prata med backenden (`searchTalks`, `chat`, `vectorSearch`, `getMeta`). |
| `frontend/src/components/*` | UI-komponenter i React/TypeScript för sök, resultat, chat, statistik. |

---

## 🗄️ ArangoDB och ArangoSearch

- **Kollektioner**: rådata om tal, talare och debatter lagras i Arango-kollektioner.
- **Views**: exempelvis `talks_view` indexerar textfält med analysatorn `text_sv`. Alla fritextfrågor går via vyn.
- **AQL-byggstenar**:
  - `FOR doc IN talks_view`
  - `SEARCH` med `ANALYZER`, `PHRASE` eller token-matchning.
  - `FILTER` för parti, år, kategori och talare.
  - `SORT BM25(doc)` eller `SORT doc.datum` beroende på begärd sortering.
  - `LIMIT @offset, @limit` för paginering.
- **Metadata**: hämtas via dedikerade queries i `_arango/queries/meta.py` (t.ex. `COLLECT party = doc.party RETURN DISTINCT party`).

---

## 🧠 ChromaDB för vektorsök

- Embeddings genereras via `scripts/build_embeddings.py` som:
  1. Läser dokument från Arango via `arango_client`.
  2. Delar text i chunkar (`_chromadb/embeddings.py`).
  3. Beräknar embeddings (vanligen med `_llm` eller annan embeddingsgenerator).
  4. Sparar chunkar + metadata i en Chroma-samling.
- Chatten hämtar liknande chunkar med `collection.query(query_texts=[...], n_results=top_k)` och använder resultaten i prompten.

---

## 🔧 Utvecklingsflöde

| Steg | Befallning | Kommentar |
|------|------------|-----------|
| Starta backend i utvecklingsläge | `uvicorn backend.app:app --reload --port 8000` | Kör i projektroten. |
| 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 Arango-inmatning | `python -m scripts.ingest_arguments` | Läser in tal/metadata i Arango. |

---

## 🧪 Felsökning och tips

- **Arango-anslutning**: kör `python arango_client.py` eller `arangosh --server.endpoint tcp://127.0.0.1:8529`.
- **Kontrollera AQL**: använd ArangoDB Web UI eller `arangosh` för att testa samma query som `SearchService` byggde.
- **Chroma-status**: kontrollera `persist_directory` i `_chromadb/client.py`; ta bort katalogen om du behöver återskapa samlingen.
- **Embeddings**: kör `python -m scripts.build_embeddings --limit 20` för att uppdatera Chroma när nytt material importeras.
- **LLM-svar**: logga prompt och kontext i `backend/chat.py` om svaren känns irrelevanta.
- **React/TypeScript**: använd `useQuery` för GET, `useMutation` för POST och typsätt API-kontrakt via `frontend/src/types.ts`.

---

## 🤖 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).