digithings docs.

Overview

A LangGraph state machine routes each request to the right sub-graph — quant research, retrieval, or chat — through conditional edges keyed on the request profile and the run's state. DIGI_SUPERVISOR=1 adds an entry node that stamps the run and enforces a recursion budget; it does not pick the branch, and unset, requests enter the research graph directly.

Speaks the OpenAI API so existing clients work unchanged; LiteLLM handles routing, caching, and checkpointed state across hops.

Authentication

Endpoints accept a digikey-issued RS256 JWT in `Authorization: Bearer`. When no JWKS is configured the service runs in passthrough mode (dev/test only). `/healthz` and `/v1/status` are auth-exempt.

Run locally

docker compose up -d digigraph

uvicorn digigraph.server:app

FastMCP streamable-http (workflow, chat, thread_state, list_orchestrator_tools)

Configuration

Endpoints

Base URL $DIGIGRAPH_URL — the service URL from docker-compose.yml.

{ "ok": true }

curl $DIGIGRAPH_URL/healthz

{
  "service": "digigraph",
  "project_name": "demo",
  "agents_enabled": true,
  "llm_mode": "test",
  "mcp_enabled": true,
  "workflow_profile": "default"
}

curl $DIGIGRAPH_URL/v1/status

curl -X POST $DIGIGRAPH_URL/workflow \
  -H "Authorization: Bearer $JWT" -H "content-type: application/json" \
  -d '{"prompt": "Backtest a momentum strategy on AAPL"}'

curl -X POST $DIGIGRAPH_URL/v1/chat/completions \
  -H "Authorization: Bearer $JWT" -H "content-type: application/json" \
  -d '{"model":"digigraph-rag","messages":[{"role":"user","content":"hi"}]}'

curl $DIGIGRAPH_URL/v1/models -H "Authorization: Bearer $JWT"

MCP tools

• workflow(prompt, thread_id?)Run the full research + backtest graph; returns a JSON WorkflowResult.
• chat(message, thread_id?, model?)Single-turn chat via /v1/chat/completions.
• thread_state(thread_id)Return the LangGraph checkpoint state for a thread.
• list_orchestrator_tools()List registered orchestrator tool names.
• list_orchestrator_tools_detailed()Tool manifest: name, tags, dynamic_schema flag.

Stack

Related

Links

Overview

Atlas runs scheduled research and Hermes turns it into signals; backtests run on a real NautilusTrader engine with Optuna driving the parameter search.

Every run writes an append-only audit trail and a tearsheet. No broker adapter ships wired — the IB, Alpaca, and QuantConnect adapters are declared stubs, so reaching a live venue is your own deliberate integration.

Authentication

Backtest/optimize/pipeline routes accept a digikey JWT (optional in passthrough mode). Async jobs stream progress over SSE.

Run locally

docker compose up -d digiquant

uvicorn digiquant.server:app

Configuration

Endpoints

Base URL $DIGIQUANT_URL — the service URL from docker-compose.yml.

[{ "name": "mean_reversion_tech", "aliases": [], "description": "...", "default_params": {} }]

curl $DIGIQUANT_URL/strategies

curl -X POST $DIGIQUANT_URL/run_backtest \
  -H "Authorization: Bearer $JWT" -H "content-type: application/json" \
  -d '{"strategy_name":"mean_reversion_tech","symbols":["AAPL"]}'

{ "job_id": "..." }

curl -N $DIGIQUANT_URL/backtest/$JOB_ID/progress

Stack

Related

Links

Overview

One client over Chroma or Azure AI Search, with backend-neutral entities so you swap engines without touching business code.

Dense, sparse, and hybrid retrieval are first-class; BeautifulSoup and pdfplumber handle ingest, Polars throughout.

Authentication

All query/ingest routes require a digikey JWT carrying the matching scope.

Run locally

docker compose up -d digisearch

uvicorn digisearch.server:app

digisearch mcp   (FastMCP streamable-http: digisearch_query, digisearch_research_turn)

Configuration

Endpoints

Base URL $DIGISEARCH_URL — the service URL from docker-compose.yml.

curl -X POST $DIGISEARCH_URL/query \
  -H "Authorization: Bearer $JWT" -H "content-type: application/json" \
  -d '{"text":"momentum factor","index_name":"default","top_k":5}'

{ "doc_id": "...", "chunks_created": 12, "index_name": "default", "status": "ok" }

MCP tools

• digisearch_querySearch documents; returns formatted hits with score + preview.
• digisearch_research_turnComposite research turn with citations (needs digisearch[agent]).

Stack

Related

Links

Overview

A Next.js and React BFF streaming digigraph through the Vercel AI SDK, your key forwarded per request — never stored, never logged.

NextAuth handles identity; Postgres and Drizzle persist sessions for humans and agents alike.

Authentication

The deployed digithings.ai chat is an agentic Cloudflare Pages Function (no login) that grounds answers in the digivault docs. The full Docker BFF additionally authenticates users via NextAuth and exchanges a BFF session for a digikey JWT to call digigraph.

Run locally

docker compose --profile digichat up -d

make digichat-dev   # Next.js dev server with hot reload

Configuration

Endpoints

Base URL $DIGICHAT_URL — the service URL from docker-compose.yml.

{ "ok": true }

{ "content": "…grounded answer…", "tool_calls": [] }

curl -X POST $DIGICHAT_URL/api/chat \
  -H "content-type: application/json" \
  -d '{"messages":[{"role":"user","content":"What does digigraph do?"}]}'

Notes

• Committed OpenAPI: docs/openapi/digichat.json (authored; path existence checked in tests/contracts).
• Self-host: make up-ghcr-digichat pulls ghcr.io/digithings-ai/digichat (see infra/self-host/compose.ghcr.yml).

Stack

Related

Links

Overview

RS256-signed JWTs with a published JWKS, organization and project membership, and row-level scopes baked into the token.

SQLAlchemy over Postgres stores keys, bcrypt hashes them, and an optional Redis blocklist handles revocation.

Authentication

digikey is the issuer. Admin routes require the `DIGIKEY_ADMIN_TOKEN` bearer; token exchange takes a raw API key or a BFF-session grant. JWKS and /healthz are public.

Run locally

docker compose up -d digikey

uvicorn digikey.server:app

Configuration

Endpoints

Base URL $DIGIKEY_URL — the service URL from docker-compose.yml.

curl $DIGIKEY_URL/.well-known/jwks.json

{ "key_prefix": "dgk_live_…", "api_key": "dgk_live_…(once)", "id": "<uuid>" }

curl -X POST $DIGIKEY_URL/v1/admin/keys \
  -H "Authorization: Bearer $DIGIKEY_ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{"tenant_slug":"acme","scopes":["digiquant:backtest"]}'

{ "access_token": "<JWT>", "token_type": "Bearer", "expires_in": 900 }

curl -X POST $DIGIKEY_URL/v1/oauth/token \
  -H "content-type: application/json" \
  -d '{"grant_type":"api_key","api_key":"'"$DIGI_API_KEY"'"}'

{ "revoked": true, "jtis_invalidated": 3 }

Stack

Related

Links

Overview

Structured logging, Prometheus metrics, and OpenTelemetry spans thread through every request so a multi-hop run is traceable end to end.

Audit events record a prompt's length and its IDs, never the prompt itself — tail events.jsonl and check. Optional LangSmith export runs a regex PII redactor on the way out.

Authentication

Status and metrics are public diagnostics. Tracing is a library wrapper, not an HTTP surface.

Run locally

docker compose up -d digismith

uvicorn digismith.server:app

Configuration

Endpoints

Base URL $DIGISMITH_URL — the service URL from docker-compose.yml.

{
  "version": "0.1.0",
  "tracing_configured": true,
  "langsmith_sdk_installed": true,
  "langsmith_host": "api.smith.langchain.com",
  "request_id": "..."
}

curl $DIGISMITH_URL/v1/status

Public interface

• from digismith.trace import traceable@traceable("name") wraps a function with langsmith.traceable when LANGSMITH_API_KEY is set; otherwise a no-op. PII is redacted from span inputs/outputs.
• from digismith.config import tracing_enabledReturns True when tracing is configured (key set + SDK importable).

Notes

• Span attributes SHOULD include workflow_id, request_id, session_id, job_id.
• Spans MUST NOT include raw prompts/completions, secrets, or full document bodies.

Stack

Related

Links

Overview

A heartbeat service that keeps agents running: Atlas runner scheduling and drift detection, calling digigraph over HTTP on an interval.

Every action lands in an append-only audit log, and it runs no LLM of its own.

Authentication

CLI-only — no HTTP service / OpenAPI. Heartbeat runner pings service health and appends an immutable audit log. Container image: ghcr.io/digithings-ai/digiclaw (Compose profile heartbeat).

Run locally

python -m digiclaw            # one cycle
docker compose --profile heartbeat up -d heartbeat
# GHCR: docker compose -f docker-compose.yml -f infra/self-host/compose.ghcr.yml --profile heartbeat up -d

Configuration

Public interface

• python -m digiclawRun one heartbeat cycle: health-check services, run an auth-gated drift check, and (on drift) trigger re-optimization.
• audit_log(event_type, agent_id, payload)Append one redacted JSON line to the audit log.

Notes

• Audit event types: heartbeat, reoptimize_triggered, reoptimize_completed, reoptimize_failed, drift_check_skipped.
• Keys matching password / api_key / token / secret are redacted before write.

Stack

Related

Links

Overview

Not a service but a deliberately minimal library: request-ID middleware and logging, CORS and error handlers, an audit redaction helper, and a Prometheus metrics endpoint.

Imported by every other module so they all behave consistently, with optional OpenTelemetry setup. Auth middleware is digikey's job, not digibase's.

Authentication

Shared Python library imported by every service — not a network surface.

Run locally

# installed as a dependency of each service; no standalone run

Configuration

Public interface

• from digibase.errors import register_fastapi_error_handlersStandard error envelope: {error:{code,message,request_id,service}}.
• from digibase.http import outbound_service_headersBuilds X-Request-ID + Authorization headers for service-to-service calls.
• from digibase.http import install_request_id_middlewareReads/generates X-Request-ID, stores on request.state, echoes on the response.
• from digibase.audit import redact_mappingRedacts password/api_key/token/secret keys from a payload before logging.
• from digibase.metrics import install_metricsMounts Prometheus /metrics with http_requests_total / _duration / _in_flight.
• from digibase.otel import setup_otel_fastapiOptional OTel wiring; no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set.

Stack

Related

Links

Overview

An Obsidian-style vault service: it manages a folder of markdown notes with YAML frontmatter, wikilinks, tags and a folder taxonomy, and answers over HTTP rather than asking callers to walk the filesystem.

Routes cover listing, reading and creating notes, renaming with backlink repair, backlink and tag lookups, and a lint report. Two more — orchestrator_tools and orchestrator_invoke — expose the vault to digigraph as callable tools. Runs behind the `digivault` compose profile, so it is opt-in rather than up by default.

Authentication

`DigiAuthMiddleware` with a per-path scope map: digivault:read for reads and for both orchestrator routes, digivault:write for mutations. /v1/orchestrator_invoke is gated at read because most of its tools are reads — the one mutating tool re-checks digivault:write in the handler, so a read-only caller cannot reach it through the shared endpoint.

Run locally

docker compose --profile digivault up -d digivault   # opt-in profile, not up by default
digivault lint --root ./docs/vision

Configuration

Public interface

• GET /v1/notesList notes in the vault.
• GET /v1/notes/{name}Read one note — body plus parsed YAML frontmatter.
• POST /v1/notesCreate a note. Requires digivault:write.
• PATCH /v1/notes/{name}/frontmatterUpdate frontmatter in place.
• POST /v1/notes/{name}/renameRename a note and repair the wikilinks pointing at it.
• GET /v1/notes/{name}/backlinksEvery note linking to this one.
• GET /v1/tags/{tag}Notes carrying a tag.
• GET /v1/lintVault health: broken wikilinks, missing frontmatter, taxonomy drift.
• POST /v1/orchestrator_toolsTool manifest, so digigraph can discover what the vault offers.
• POST /v1/orchestrator_invokeInvoke one of those tools by name.

Notes

• The vault is a folder of markdown files — YAML frontmatter, wikilinks, tags, folder taxonomy. There is no database; the filesystem is the store.
• Its first consumer is this repository's own docs/vision/, which scripts/gen-api-vault.ts generates from the same module registry this page is built from.

Stack

Related

Links

Overview

Roadmap: a storage abstraction so business code never binds to a backend, today a session-scoped dataset manager living inside digigraph.

Run SQLite on a laptop, then swap to S3 and Postgres in production without rewriting.

Authentication

Roadmap. Today a session-scoped dataset manager lives inside digigraph; the standalone storage service is planned.

Notes

• Planned: one storage API over S3, MinIO, Postgres, or SQLite so business code never binds to a backend.
• Planned surface: digistore.configure(backend=…) + get/put/list over a backend-neutral interface.

Stack

Related

Links

Overview

Roadmap: a translation layer registering adapters that turn REST, gRPC, or bespoke transports into MCP tools.

Today MCP is built into individual modules; this keeps the stack open instead of locked to one protocol.

Authentication

Roadmap. Today MCP is built into individual modules (e.g. digisearch-mcp).

Notes

• Planned: a protocol bridge registering adapters that turn REST, gRPC, or bespoke transports into MCP tools.
• Planned surface: digilink.register_adapter("rest", …) to expose a non-native transport as MCP.

Stack

Related

Links