Developer

Three machine surfaces: HTTP/JSON, MCP, and direct Postgres. Each authenticates with a separate token from ~/auracle/.env.

HTTP API

All HTTP routes are served by the Houston container at http://localhost:1969/api/. Every route requires X-API-Key: $HOUSTON_API_KEY — no exceptions, no fallback. Cross-origin requests are rejected by default.

Forge routes

External (through Caddy TLS) URLs are /api/forge/*; Caddy strips /api/ and forwards to Houston at /forge/*. The direct Houston port (1969) is what the local-dev examples below show.

Example: filter catalog

curl -s http://localhost:1969/forge/catalog?verdict=useful \
  -H "X-API-Key: $HOUSTON_API_KEY" \
  | jq '.datasets[] | {id, provider, capability, usefulness_score, verdict}'

{ "id": 12, "provider": "polygon.io", "capability": "bars.daily",
  "usefulness_score": 87, "verdict": "useful" }
{ "id":  7, "provider": "polygon.io", "capability": "options.chains",
  "usefulness_score": 81, "verdict": "useful" }
…

Example: ambient context

curl -s http://localhost:1969/forge/ambient \
  -H "X-API-Key: $HOUSTON_API_KEY"

{
  "install_uuid": "00000000-…",
  "tier": "pro",
  "enabled": true,
  "catalog_signature": "7a3f9e1b2c4d5e6f",
  "relevant_datasets": [ … 5 entries … ],
  "system_prompt_injection": "─── Auracle ambient context …"
}

Errors

Standard problem-detail responses (application/problem+json).

MCP tools

The MCP server is a standalone process at http://localhost:7777, separate from Houston. It speaks the Model Context Protocol over streamable HTTP. Point Claude Desktop (or any MCP client) at it with Authorization: Bearer $AURACLE_MCP_TOKEN from your .env. The server negotiates api_version: 1; future versions are added additively.

Schema

Eight tables underpin the Forge. All live in the default Postgres schema; all use BIGSERIAL primary keys and timestamp-with-tz columns. Schema migrations run idempotently on every boot — new columns and tables land additively.

providers

id              BIGSERIAL PRIMARY KEY
name            TEXT NOT NULL UNIQUE
kind            TEXT NOT NULL   -- market_data | broker | llm | notification | infra
base_url        TEXT NOT NULL
auth_type       TEXT NOT NULL
openapi_url     TEXT
adapter_path    TEXT
capability_taxonomy  JSONB
registry_source TEXT NOT NULL DEFAULT 'bundled'
confidence      NUMERIC(4,3) NOT NULL DEFAULT 1.000
created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()

forge_datasets

id                  BIGSERIAL PRIMARY KEY
provider_id         BIGINT NOT NULL REFERENCES providers(id)
capability          TEXT   NOT NULL          -- e.g. 'bars.daily', 'options.chains'
name                TEXT   NOT NULL          -- human label
asset_class         TEXT                     -- equities | crypto | futures | …
grain               TEXT                     -- '1d' | '1m' | 'tick'
history_years       NUMERIC(5,2)
schema_json         JSONB NOT NULL
storage_uri         TEXT  NOT NULL           -- e.g. postgres://…  s3://…

coverage            INTEGER  CHECK (coverage BETWEEN 0 AND 100)
freshness           INTEGER  CHECK (freshness BETWEEN 0 AND 100)
completeness        INTEGER  CHECK (completeness BETWEEN 0 AND 100)
uniqueness          INTEGER  CHECK (uniqueness BETWEEN 0 AND 100)
stability           INTEGER  CHECK (stability BETWEEN 0 AND 100)
trading_relevance   INTEGER  CHECK (trading_relevance BETWEEN 0 AND 100)

usefulness_score    INTEGER                  -- geometric mean of the six dims
verdict             TEXT                     -- useful | marginal | poor | irrelevant
suggested_uses      JSONB                    -- array of free-text use cases
scored_at           TIMESTAMPTZ
created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()

Other tables (summary)

Compatibility matrix

Auracle ships under semver. The Forge HTTP and MCP surfaces negotiate an explicit api_version on every request — the server accepts the lowest version it supports and the client adapts.

Within a major version, removed fields appear as null for older clients; new fields are ignored. Across majors, the schema migrates additively and the API version bumps explicitly.

Contributing

The bundled providers registry lives in auracle/providers/registry.py as a tuple of ProviderSpec dataclasses. To add a provider:

1. Fork the auracle-installer repo (the registry will be moved here in 2.2).
2. Add a ProviderSpec entry. Required fields: name, kind, base_url, auth_type, key_prefixes (a tuple of regex patterns), capabilities (a tuple of capability strings).
3. If the provider needs a custom adapter (most do), drop a Python module under auracle/adapters/<name>.py conforming to the ProbeAdapter protocol.
4. Add a registry test in tests/test_providers_registry.py with a sample key string that classify_key should match.
5. Open a PR. The CI runs the test matrix; merging requires green CI and one approver.

# Example: adding "twelvedata"
ProviderSpec(
    name="twelvedata",
    kind="market_data",
    base_url="https://api.twelvedata.com",
    auth_type="api_key",
    key_prefixes=(r"^[a-f0-9]{32}$",),
    capabilities=("bars.daily", "bars.intraday", "fundamentals"),
    adapter_path="auracle.adapters.twelvedata",
    docs_url="https://twelvedata.com/docs",
),