demon-api

Golang API service (Hertz) for Laplace Demon analyzer. It exposes:

• Minimal YBTTree APIs for representing token/asset composition as a tree.
• Separate YBT meta APIs for descriptive metadata (name, description, tags, links).

This split keeps the YBTTree schema minimal and LLM‑friendly, while meta stays independent.

Run

• Copy .env.example to .env.local and fill values (OPENAI_API_KEY, OPENAI_MODEL). Do NOT commit secrets.
• Option A: export env in terminal, then run go run ./cmd/server
• Option B: in GoLand with EnvFile plugin, enable EnvFile in your Run config and load .env.local (and optionally .env.example). Then run the shared "Run Server" config.
• Server listens on :8080 by default, overridable via config.

Endpoints

• Ops

  • GET /healthz
  • GET /readyz

• ybt/tree (under /api/v1)

  • GET /api/v1/ybt/tree → { "ids": ["..."] }
  • GET /api/v1/ybt/tree/:id → Tree
  • POST /api/v1/ybt/tree body: { "id": "ybt:proj:token", "root": Node } → upsert
  • PUT /api/v1/ybt/tree/:id body: { "root": Node } → update
  • DELETE /api/v1/ybt/tree/:id

  Types:

  • Node: { "id": string, "label": string, "children": [Node] }
  • Tree: { "id": string, "root": Node }

• YBT Meta (under /api/v1)

  • GET /api/v1/ybt/meta → { "items": [Meta] }
  • GET /api/v1/ybt/meta/:id → Meta
  • PUT/POST /api/v1/ybt/meta/:id body: Meta → upsert
  • DELETE /api/v1/ybt/meta/:id

  Meta: { "id": string, "project": string, "symbol": string, "links": {"key":"url"}, "updated_at": RFC3339 }

GoLand setup (optional)

• Use the shared run configs under .idea/runConfigurations or create your own.
• Install the EnvFile plugin and load variables from .env.local (and .env.example if desired). Shared run configs avoid hardcoding env vars.

Rationale: separate tree and meta

• Minimal surface for tree editing by LLM agents; avoids noisy fields.
• Independent evolution and caching of meta (docs/risks/links) without touching composition.
• Cleaner permissioning and ownership: one agent builds trees, another curates meta.
• Easier validation and testing: structural vs descriptive concerns decoupled.

Code Structure

• internal/config: config loader (YAML, env) with defaults
• internal/infra/hertz: Hertz initialization (port, logger)
• internal/infra/provider: process-wide providers (YBT stores)
• internal/router: routing and middleware
• internal/handler: HTTP handlers (router calls into these)
• internal/ybt_tree: minimal tree types and in-memory store
• internal/ybt_meta: meta types and in-memory store
• cmd/server: server entrypoint
  • Initializes Hertz and providers once; handlers assume pre-initialized stores