Company Context Assistant

A hosted chat app for asking questions over messy company records.

The app is built for the Codos take-home task. It lets a business user sign in, ask natural-language questions, continue multi-turn conversations, open referenced files, and get plain-language answers backed by original source documents.

What It Does

• Answers questions from the bundled data/ records.
• Preserves chat history across reloads and redeploys when Vercel Blob is configured.
• Resolves ambiguous entities such as similar people, regions, products, customers, and initiatives.
• Uses normalized records for interpretation, but cites only original documents in user-facing answers.
• Shows references with [1], [2] style citations and a file preview UI.
• Avoids exposing implementation details in the business-user chat experience.

Architecture

Next.js chat UI
  -> username/password session
  -> chat history store
  -> /api/query
  -> isolated Vercel Sandbox
  -> agent runtime over a POSIX-style workspace
  -> sourced answer with original-document references

The core design decision is to keep the workspace filesystem-shaped:

AGENTS.md
data/
  original company records
  normalized/
    entities.jsonl
    facts.jsonl
    causal_chains.jsonl

data/normalized/ is the preferred interpretation layer for aliases, entity resolution, stale facts, conflicts, and causal chains. It is not shown as answer evidence. Final answers cite the original company documents under data/.

This keeps the implementation simple now and leaves a clean path to a remote POSIX-compatible store later, where users or ingestion jobs can sync files without changing the query interface.

Key Product Rules

• Answer from local company records, not model memory.
• Use resolved canonical entity names in answers.
• Ask for clarification when ambiguity materially changes the answer.
• Prefer newer or more authoritative evidence when records conflict.
• Explain uncertainty and conflicts when they matter.
• Cite original documents only.
• Keep answers readable for non-technical business users.

Local Setup

Install dependencies:

npm install

Create local env:

cp .env.example .env.local

Set either:

OPENAI_API_KEY=...

or shared ChatGPT-plan auth:

codex login
base64 -i ~/.codex/auth.json | tr -d '\n'

Paste the encoded value into:

CODEX_AUTH_JSON_B64=...

The UI uses username/password auth. Set explicit credentials with:

APP_USERNAME=...
APP_PASSWORD=...
AUTH_SECRET=...

Run the app:

npm run dev

Run a local command-line query:

npm run query:local -- "What is the current status of Project Confluence?"

Regenerate the normalized interpretation layer with an LLM resolution pass:

npm run normalize

Deploy

Deploy to Vercel with:

npx vercel deploy --yes

Required environment:

APP_USERNAME=...
APP_PASSWORD=...
AUTH_SECRET=...
CODEX_AUTH_JSON_B64=...

OPENAI_API_KEY can be used instead of CODEX_AUTH_JSON_B64 for model access.

Optional but recommended:

BLOB_READ_WRITE_TOKEN=...

Without Vercel Blob, chat history is stored locally under .internal/chats/ and may not survive serverless restarts or redeploys. With Vercel Blob attached, past conversations remain available in the UI.

Verify

Build:

npm run build

Run hosted smoke tests against a Vercel Preview:

VERCEL_DEPLOYMENT=https://your-preview.vercel.app npm run test:vercel

Run entity-resolution evals:

VERCEL_DEPLOYMENT=https://your-preview.vercel.app npm run test:entities

The smoke test covers login, greeting behavior, sourced answers, multi-turn follow-up, persisted chat history, and source preview. The entity evals cover ambiguous people, stale claims, product distinctions, regional metrics, and original-document citations.

Implementation Notes

• app/api/query/route.ts is the main question-answering endpoint.
• components/chat-app.tsx contains the mobile-friendly chat UI.
• components/ai-elements/message.tsx wraps the off-the-shelf Streamdown/AI Elements-style renderer used for assistant answers and markdown source previews.
• lib/chat/store.ts stores and retrieves conversations.
• lib/codex-sandbox.ts runs the isolated hosted agent process.
• lib/prompt.ts builds the runtime answer contract.
• AGENTS.md defines repository-level reasoning and citation rules.
• scripts/normalize-data.ts asks Codex CLI to inspect the original data/ files, generate normalized records, and then validates the returned JSONL before writing data/normalized/.
• SOLUTION.md has the deeper architecture write-up and tradeoffs.

Known Gaps

• Full per-workspace permission management is not implemented in this take-home.
• The hosted runtime installs the agent CLI at execution time; a production version should use a prebuilt sandbox image.
• The normalization pipeline is intentionally small for the homework. In production it should be extended with OCR/PDF/table extraction, review queues, confidence thresholds, and incremental sync.
• Clarification persistence is specified in the agent rules, but a dedicated UI flow for reviewing and approving clarifications is future work.