# Open District — Agent Instructions

## Section Index

| # | Section | Anchor |
|---|---------|--------|
| 1 | [Product Summary](#product-summary) | `#product-summary` |
| 2 | [MCP Endpoint + Config](#mcp-endpoint--config) | `#mcp-endpoint--config` |
| 3 | [MCP Tools (10)](#mcp-tools) | `#mcp-tools` |
| 4 | [REST/API Endpoints](#restapi-endpoints) | `#restapi-endpoints` |
| 5 | [Connector Catalog](#connector-catalog) | `#connector-catalog` |
| 6 | [Event Store Facts](#event-store-facts) | `#event-store-facts` |
| 7 | [Audit/Governance Surface](#auditgovernance-surface) | `#auditgovernance-surface` |
| 8 | [Pricing + Signup](#pricing--signup) | `#pricing--signup` |
| 9 | [Current Status](#current-status) | `#current-status` |

---

## Product Summary

Open District connects public data, enterprise systems, personal context, memory, reasoning, and governed action in one secure platform. Every fact has a source, every answer has citations, every action has auditability. Available now: append-only event store (Postgres + ClickHouse mirror), 33 source connector templates (REST manifests, OAuth, webhooks, 17+ public datasets), federated SQL with read-only gate, semantic + lexical search (Qdrant, 1024-dim), entity graph with cited paths, pipeline engine (scheduled DAG jobs, sandboxed WASM UDFs), MCP server (10 tools), append-only audit log, SSO (OIDC), PASETO sessions, scoped API keys. In development: human-approval workflow for governed actions, governed write-backs, standing subscriptions. Platform direction: prediction/forecasting, cross-entity network intelligence, connectors (U.S. Census, SEC EDGAR, court opinions, Jira, Snowflake, direct Postgres). Pricing: $1/user/month. Early access: request via https://opendistrict.org/#access.

---

## MCP Endpoint + Config

- **URL:** `https://mcp.opendistrict.org/mcp`
- **Transport:** Streamable HTTP
- **Auth:** Bearer token via scoped API key issued in-app at `app.opendistrict.org`
- **Scopes:** `admin`, `api_keys`, `read`

```json
{
  "mcpServers": {
    "opendistrict": {
      "url": "https://mcp.opendistrict.org/mcp",
      "headers": {
        "Authorization": "Bearer $OD_API_KEY"
      }
    }
  }
}
```

---

## MCP Tools

All tools require valid Bearer token. All reads are gated; all actions are audited.

### 1. `query`

Federated SQL query with read-only gate. Executes across connected sources without write side-effects.

```
query(sql: string, params?: Record<string, any>) -> { rows: any[], columns: string[], row_count: number, sources: string[], duration_ms: number }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| sql | string | yes | Read-only SQL statement |
| params | Record<string, any> | no | Parameterized query bindings |

### 2. `search`

Semantic + lexical search across indexed data. Hybrid retrieval with Qdrant (1024-dim embeddings) and lexical fallback.

```
search(q: string, filters?: { source?: string, entity_type?: string, date_from?: string, date_to?: string }, limit?: number) -> { results: SearchResult[], total: number }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| q | string | yes | Search query (natural language or keywords) |
| filters | object | no | Source, entity type, date range filters |
| limit | number | no | Max results (default 20) |

### 3. `schema`

Introspect available schemas, types, and table structures across connected sources.

```
schema(source?: string, table?: string) -> { schemas: SchemaDef[], tables?: TableDef[], columns?: ColumnDef[] }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| source | string | no | Scope to specific source |
| table | string | no | Scope to specific table |

### 4. `catalog`

Browse and search the connector catalog. Lists available source templates, their types, and sync status.

```
catalog(type?: string, category?: string, search?: string) -> { connectors: ConnectorTemplate[], count: number }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | no | Filter by connector type (rest, oauth, webhook, db) |
| category | string | no | Filter by category (public, enterprise, personal) |
| search | string | no | Search connector names and descriptions |

### 5. `topology`

Inspect the entity graph topology. Returns node/edge counts, entity types, and relationship summaries.

```
topology(entity_type?: string, depth?: number) -> { nodes: number, edges: number, types: EntityType[], relationships: RelationshipSummary[] }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| entity_type | string | no | Scope to specific entity type |
| depth | number | no | Traversal depth for relationship summary (default 1) |

### 6. `metrics`

Query platform usage and data freshness metrics. Tenant-scoped statistics on queries, syncs, and coverage.

```
metrics(scope?: "tenant"|"system", period?: string) -> { queries_total: number, syncs_total: number, sources_active: number, data_freshness: Record<string, string> }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| scope | enum | no | tenant (default) or system |
| period | string | no | Time period (e.g. "7d", "30d", default "7d") |

### 7. `entities`

Entity graph lookup with cited paths. Returns entities and their provenance chains.

```
entities(id?: string, type?: string, name?: string, depth?: number) -> { entities: Entity[], edges: Edge[], citations: Citation[] }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | no | Specific entity ID |
| type | string | no | Entity type filter |
| name | string | no | Fuzzy name match |
| depth | number | no | Graph traversal depth (default 1) |

### 8. `pipelines`

Manage scheduled DAG jobs. Inspect pipeline definitions, runs, and status.

```
pipelines(action: "list"|"get"|"trigger", id?: string) -> { pipelines?: Pipeline[], run?: PipelineRun, triggered?: boolean }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| action | enum | yes | list, get, or trigger |
| id | string | conditional | Pipeline ID (required for get/trigger) |

### 9. `events`

Query append-only event store. Temporal provenance on all facts.

```
events(filter?: { source?: string, entity_id?: string, event_type?: string, since?: string, until?: string }, cursor?: string, limit?: number) -> { events: Event[], next_cursor?: string }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| filter | object | no | Source, entity, type, time range |
| cursor | string | no | Pagination cursor |
| limit | number | no | Max events (default 50) |

### 10. `audit`

Query audit log entries. Every query and action is recorded.

```
audit(filter?: { actor?: string, action?: string, resource?: string, since?: string, until?: string }, cursor?: string, limit?: number) -> { entries: AuditEntry[], next_cursor?: string }
```

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| filter | object | no | Actor, action, resource, time range |
| cursor | string | no | Pagination cursor |
| limit | number | no | Max entries (default 50) |

---

## REST/API Endpoints

| Method | URL | Auth | Description |
|--------|-----|------|-------------|
| GET | `https://app.opendistrict.org/api/health` | none | Service health (public) |
| POST | `https://mcp.opendistrict.org/mcp` | Bearer | MCP Streamable HTTP endpoint |
| GET | `https://app.opendistrict.org/login` | none | SSO/OIDC login redirect |
| POST | `https://app.opendistrict.org/api/keys` | Bearer (admin) | Issue scoped API key |
| DELETE | `https://app.opendistrict.org/api/keys/:id` | Bearer (admin) | Revoke API key |

---

## Connector Catalog

**Total:** 33 source connector templates

### By Type

| Type | Count | Description |
|------|-------|-------------|
| REST manifests | ~15 | Declarative JSON configs for REST APIs |
| OAuth | ~8 | OAuth 2.0 flows for SaaS platforms |
| Webhooks | ~5 | Inbound event receivers |
| Direct DB | ~5 | Postgres, Snowflake (direction) |

### By Category

| Category | Examples | Status |
|----------|----------|--------|
| PUBLIC | Government open data, regulatory filings, census, court records | 17+ available now |
| ENTERPRISE | SaaS APIs, databases, internal tools, Jira, Snowflake | Partial now; expanding |
| PERSONAL | Email, calendar, documents, notes | In development |

### Public Datasets (Available Now)

Government portals, regulatory agencies, open data initiatives, geospatial datasets, legislative records, campaign finance, environmental monitoring, transportation, education statistics, health statistics, crime statistics, property records, business registries, patent databases, academic publications.

### Connectors In Development / Direction

U.S. Census, SEC EDGAR, court opinions, Jira, Snowflake, direct Postgres, standing subscriptions.

---

## Event Store Facts

- **Storage:** Append-only event store backed by Postgres
- **Analytics mirror:** ClickHouse for analytical queries over large event ranges
- **Immutability:** Events are never updated or deleted; corrections are new events referencing originals
- **Temporal provenance:** Every fact carries source timestamp, ingestion timestamp, and source reference
- **Audit integration:** Every query against the event store writes an audit log entry
- **Schema evolution:** Events carry schema version; readers handle backward-compatible evolution

---

## Audit/Governance Surface

| Control | Implementation | Status |
|---------|---------------|--------|
| Audit log | Append-only; every query, every action | Available |
| Row-level security | Postgres RLS policies per tenant | Available |
| Scoped API keys | Scopes: `admin`, `api_keys`, `read` | Available |
| Read-only gate | Federated SQL rejects write statements | Available |
| SSO | OIDC providers | Available |
| Session tokens | PASETO (v4.public) | Available |
| Human-approval workflow | Governed actions require explicit approval | In development |
| Governed write-backs | Audited, approved writes to external systems | In development |
| Standing subscriptions | Recurring data syncs with governance | In development |

---

## Pricing + Signup

- **Price:** $1 per user per month
- **Early access:** Manual account grants (humans review each request)
- **Request access:** https://opendistrict.org/#access
- **Email:** hello@opendistrict.org
- **Sign in:** https://app.opendistrict.org/login
- **API keys:** Issued per tenant in-app with explicit scopes

---

## Current Status

Verified against running system as of 2026-08-21.

### Available Now

- Append-only event store (Postgres + ClickHouse mirror)
- 33 source connector templates (REST manifests, OAuth, webhooks, 17+ public datasets)
- Federated SQL with read-only gate
- Semantic + lexical search (Qdrant, 1024-dim)
- Entity graph with cited paths
- Pipeline engine (scheduled DAG jobs, sandboxed WASM UDFs)
- MCP server (10 tools)
- Append-only audit log
- SSO (OIDC)
- PASETO sessions
- Scoped API keys

### In Development

- Human-approval workflow for governed actions
- Governed write-backs
- Standing subscriptions

### Platform Direction

- Prediction/forecasting
- Cross-entity network intelligence (aggregate signals without exposing raw tenant data)
- Additional connectors: U.S. Census, SEC EDGAR, court opinions, Jira, Snowflake, direct Postgres