jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d3a88585fe
stemedb/ai-lookup/services/api.md
jordan 1ce4004807 feat: Complete Phase 2 (The Cortex) - query, lens, and API layers 
This commit adds the read path (Cortex) to complement the write path (Spine):

## Crates
- stemedb-api: HTTP API with axum + utoipa OpenAPI
  - /v1/assert, /v1/query, /v1/epoch, /v1/skeptic, /v1/trace, /v1/audit
  - Metered endpoints with quota enforcement
  - Ed25519 signature verification
- stemedb-lens: Truth resolution lenses
  - RecencyLens, ConsensusLens, ConfidenceLens
  - VoteAwareConsensusLens (Ballot Box pattern)
  - TrustAwareAuthorityLens (The Hive pattern)
  - SkepticLens (conflict analysis)
  - EpochAwareLens (paradigm-safe queries)
- stemedb-query: Query engine with materialized views

## Storage Extensions
- VoteStore: Vote aggregation with cached counts
- TrustRankStore: Agent reputation with decay
- AuditStore: Query audit trail
- IndexStore: SP/P/S index structures
- SupersessionStore: Epoch supersession chains

## SDKs
- sdk/go/steme: Go HTTP client with Ed25519 signing
- sdk/go/adk: ADK-Go tools for AI agents

## Documentation
- Updated CLAUDE.md, architecture.md, roadmap.md
- New ai-lookup entries for all services
- Use case docs for consumer health intelligence
- Arena roadmap for simulation advancement

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-01 13:22:44 -07:00

2.6 KiB
Raw Blame History

API Surface

Last Updated: 2026-02-01 Confidence: High

Summary

Episteme exposes an HTTP API via axum with auto-generated OpenAPI 3.1 documentation. The API is a thin layer that wires HTTP handlers to existing library crates (QueryEngine, Ingestor, VoteStore). Documentation is generated from the same Rust types used for serialization via utoipa derive macros.

Key Facts:

  • Framework: axum with utoipa-axum for OpenAPI integration
  • Crate: stemedb-api
  • DTO layer converts between internal rkyv types and public serde JSON types
  • OpenAPI 3.1 spec auto-generated at /api-doc/openapi.json
  • Interactive docs via Swagger UI at /swagger-ui (dev mode)
  • gRPC deferred; HTTP/JSON is the initial interface

File Pointers:

  • crates/stemedb-api/src/lib.rs - App builder and OpenApiRouter
  • crates/stemedb-api/src/dto.rs - Request/Response types (serde + ToSchema)
  • crates/stemedb-api/src/handlers/ - Route handlers

Endpoints

Method Path Description Status
POST /v1/assert Submit signed assertion, writes to WAL ✅ Implemented
POST /v1/epoch Create new epoch (paradigm) with content-addressed ID ✅ Implemented
POST /v1/vote High-throughput vote submission ✅ Implemented
GET /v1/query Resolve assertions via Lens ✅ Implemented
GET /v1/skeptic Conflict analysis (Trust but Verify) ✅ Implemented
GET /v1/health Service health check ✅ Implemented
GET /v1/audit/queries List query audit trail ✅ Implemented
GET /v1/audit/query/{id} Get specific query audit ✅ Implemented
GET /v1/trace Trace assertion lineage ✅ Implemented
GET /v1/meter/quota Check remaining quota ✅ Implemented
POST /v1/meter/quota/limit Set custom quota limit (admin) ✅ Implemented
GET /api-docs/openapi.json OpenAPI 3.1 spec ✅ Implemented
GET /swagger-ui Interactive API docs ✅ Implemented

DRY Type Pipeline

stemedb-core types (rkyv)       ← Internal storage format
    |
    | impl From<> / Into<>
    v
stemedb-api DTOs (serde + ToSchema)  ← Public API contract
    |
    | utoipa derive macros
    v
OpenAPI 3.1 JSON                ← Auto-generated spec
    |
    | Widdershins (CI)
    v
Slate markdown                  ← Published docs

Related Topics