srr84/agent-data-layer

1---2title: Agent-Readable Data Layer POC3emoji: 🔎4colorFrom: indigo5colorTo: gray6sdk: docker7app_port: 78608pinned: false9short_description: AI that answers from your data without making things up10---11 12# Agent-Readable Data Layer13 14**An AI agent that answers from your data — without making things up.**15 16AI agents are useful over business data right up until they hallucinate — inventing a17stock level, a store, or a number that was never in the source. This is a small, working18system that removes that failure mode by construction: the agent can only reach data19through a fixed set of typed, parameterized tools — never a free-form query it could20fabricate — and every fact it returns comes stapled to a pointer back to the exact source21record it came from. When a question falls outside what the data can answer, it abstains22and says so, instead of guessing.23 24The guarantee is structural, not a prompt or a politeness setting — there is no path for an25ungrounded answer to slip through, and that is enforced by an automated test suite on every26change. It is already built and deployed live on a **$0 stack**, with the underlying model27swappable between a local engine and a hosted one.28 29> **Want to see it answer live?** The interactive question-and-answer path is a 2-minute30> screen-share — happy to walk through it against your data and use case.31 32## What you're looking at33 34This page is the **live deployment** of the system. It is an infrastructure component — a35typed data layer that an AI agent answers *through* — so this URL is its health/status36surface, not a consumer chat box:37 38- `GET /healthz` → `200 {"status":"ok", ...}` once the bundled data + index load.39- `GET /metrics` → operational metrics as JSON.40 41There is deliberately **no public free-text endpoint**. The question-answering surface is an42in-process typed tool API, exercised by the eval harness and the live demo — keeping it43in-process is part of how the system stays contained.44 45## How it guarantees it won't fabricate46 47- **Tools only, no raw query.** The agent reaches data only through a fixed, typed,48  parameterized tool set. There is no free-text query path for it to invent — that's a type49  error, not a code-review convention.50- **Provenance on every fact.** Every value returned is attached *by code* to a pointer to51  the exact source record. The language model selects a tool and writes prose — it never52  writes the value or its source.53- **Abstains when it can't ground.** An out-of-coverage question returns a typed "can't54  answer that from this data," never a fabricated one.55 56## Run modes57 58- **`RUN_MODE=demo_local`** (the $0 path, local only): the answer path reaches a local59  Ollama OpenAI-compatible endpoint (`http://localhost:11434/v1`, model60  `qwen2.5:7b-instruct`). This is the 90-second local demo; it is not this Space (a remote61  Space cannot reach your localhost).62- **`RUN_MODE=deployed`** (this Space): the answer path uses a hosted OpenAI-compatible63  endpoint via `MODEL_BASE_URL` / `MODEL_API_KEY` / `MODEL_NAME`. The validator rejects a64  `localhost` / `host.docker.internal` base URL in this mode.65 66## Under the hood67 68Built from the repo `Dockerfile` (`python:3.12-slim`, non-root, precomputed index baked at69image-build time). The container binds `$PORT` → `$APP_PORT` → `7860` (HF Spaces70convention) and runs `python -m agent_data_layer.app.server`. Deploy is from CI on the71release path (`.github/workflows/ci.yml`); the same containment gates run on every change.72The `MODEL_API_KEY` is never committed — it lives only in the Space repository secret and73the CI secret store.74 75*Source code and the full technical write-up (WALKTHROUGH / CODE_TOUR with architecture76diagrams) are available on request.*77