# ContextBuilder (ctx)

Context-as-a-Service MCP server for Hengam's multi-agent system. Maintains app-isolated, structured, provenance-backed context for Shopify apps and delivers "just enough context" to other agents.

## Features

- **App-scoped context**: Isolated context for 4 Shopify apps (Notify Me!, Subi, Discounty, Convi)
- **Agentic Graph Memory**: Graph-based retrieval with multi-hop traversal, not just vector search
- **Hybrid delivery**: Push starter context bundles + Pull targeted context slices
- **Observation Masking**: Budget-aware compression with full transparency on what was included/excluded
- **Provenance tracking**: Every statement traceable to source URL + snapshot timestamp + content hash
- **Configurable LLM**: Provider-agnostic (OpenAI, Anthropic, Gemini) with editable prompt templates
- **Schema-validated**: All data objects validated with Zod at boundaries

## Quick Start

```bash
# Install dependencies
pnpm install

# Set up LLM API key (at least one required for refresh)
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

# Run the MCP server
pnpm dev

# Run tests
pnpm test
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `ctx.refresh.app_sources` | Refresh and rebuild context for an app |
| `ctx.push.starter_context` | Push compact starter context bundle |
| `ctx.pull.context_slice` | Pull targeted context slice by intent |
| `ctx.get.app_state_summary` | Get app state summary + refresh status |
| `ctx.get.provenance` | Get provenance for a bundle/slice |

## Architecture

```
Ingestion → Extraction → Graph → Delivery
  fetch       summarize    build     push/pull
  parse       extract      traverse  mask
  snapshot    score        validate  provenance
```

### Pipeline Flow

1. **Ingestion**: Fetch public web sources (listing, website, help center), parse HTML, create snapshots with content hashes
2. **Extraction**: LLM-powered structuring — summarize pages, extract concepts/procedures, score observations, detect conflicts
3. **Graph**: Build context graph with nodes (features, procedures, constraints, FAQs, entities) and typed edges (explains, depends_on, resolves, etc.)
4. **Delivery**: Serve context via push (starter bundles) or pull (targeted slices) with observation masking and provenance

## Configuration

All configuration is in `config/`:

- `apps.yaml` — App source URLs and crawl settings
- `model-profiles.yaml` — LLM provider configs (model, temperature, rate limits)
- `settings.yaml` — Task bindings, budgets, masking thresholds, graph settings
- `prompt-templates/*.hbs` — Handlebars templates for all 8 LLM tasks

## Supported Apps (MVP)

| App | Listing | Website | Help Center |
|-----|---------|---------|-------------|
| Notify Me! | apps.shopify.com | notify-me.io | help.notify-me.io |
| Subi | apps.shopify.com | subi.co | help.subi.co |
| Discounty | apps.shopify.com | discounty.ai | help.discounty.ai |
| Convi | apps.shopify.com | conviapp.com | help.conviapp.com |

## Development

```bash
pnpm build          # Compile TypeScript
pnpm dev            # Run with tsx (dev mode)
pnpm test           # Run all tests
pnpm test:unit      # Run unit tests only
pnpm test:contract  # Run MCP contract tests
pnpm lint           # Type check
```

## Requirements Coverage

Implements REQ-CTX-1 through REQ-CTX-38 from the ContextBuilder agent repository spec. See `CLAUDE.md` for architecture details.