# 24 — Solomon: Retrieval & Agent Tier (Go)

**Solomon 6 of 6** · `Solomon/retrieval`, `Solomon/chains`, `Solomon/ensemble`, `Solomon/genengine`
**Stack:** Go (4,757 lines), Kafka, vector index, HTTP fetchers, RSS, SQL migrations
**Status:** Deployed as `phase2-retrieval` in the Helm chart

> **Where this sits.** The bridge between the ML work and the distributed-systems
> work. It is a **Go service** — the target language — doing ingestion,
> indexing, search, and a tool-calling agent loop with a grounding guard.

---

## Structure

```
Solomon/retrieval/
  index/    chunk.go  embed.go  search.go  store.go  service.go
  agent/    loop.go  tools.go  parser.go  calculator.go
            grounding.go  grounding_guard_test.go  trace.go  service.go
  fetcher/  extract/  rss/          ingestion
  kafkax/   kafkax.go               event transport
  llm/      searchclient/           model + search clients
  authx/    config/  migrations/  cmd/  eval/
```

Plus `chains/` (step/spec composition with a Go client), `ensemble/`
(orchestrator, members, serving, training, eval), and `genengine/`
(grammar-constrained generation, samplers, processors, context).

## The grounding guard — the part worth leading with

`agent/grounding.go` has a dedicated `grounding_guard_test.go`. A retrieval
agent's characteristic failure is answering from the model's parameters while
*appearing* to answer from the retrieved documents. A grounding guard is the
check that the answer is actually supported by what was retrieved — and having
it under test means the failure mode was anticipated rather than discovered in
production.

> "What stops your RAG system from confidently making things up?" is now a
> standard interview question. Most answers are hand-waving. This one is a
> file with a test next to it.

## The agent loop, decomposed

| File | Responsibility |
|---|---|
| `loop.go` | The iteration: think → call tool → observe → repeat, with a bound |
| `tools.go` | Tool registry and dispatch |
| `parser.go` | Parsing model output into tool calls — with its own test |
| `calculator.go` | A deterministic tool, so the loop can be tested without a model |
| `trace.go` | Execution tracing — observability for a non-deterministic system |
| `grounding.go` | The answer-support check |

`parser_test.go` and `loop_test.go` exist because both are the parts that break:
a model emits malformed tool syntax, and a loop without a bound runs forever.

## The index tier

`chunk.go` (with `chunk_test.go`), `embed.go`, `store.go`, `search.go`.
Chunking is tested because chunk-boundary bugs are silent — they do not error,
they just quietly degrade retrieval quality forever.

## Why `kafkax` matters here

The retrieval tier consumes from Kafka. That makes this the point where the ML
platform and the
[event-driven architecture](01-billboard-activity-graph.md) meet: ingestion is
not a cron job pulling feeds, it is a consumer off a log, with the same
delivery-semantics questions as everything else in this portfolio.

## Interview surface this opens

- RAG architecture: chunking strategy, embedding, retrieval, reranking
- Grounding/faithfulness checks and how you test a non-deterministic system
- Bounding an agent loop, and what you do when the bound is hit
- Deterministic tools as a testing seam for LLM systems
- Streaming ingestion off Kafka vs scheduled crawling