Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(architecture): retype the seven dashes the rules guard rejects

nirholas5eec8c7ebde2
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index d1d794fee..a08cab07c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1592,7 +1592,7 @@ Detailed above; the production hosted sniper. Its open-source, embeddable twin i
| `model-triposg` | Python/FastAPI + CUDA | High-fidelity image/sketch → 3D shape (TripoSG, VAST-AI MIT; 1.5B rectified-flow). Two modes: `image` (mesh) + `scribble` (sketch+text → mesh, CFG-distilled 16-step) powering `/forge` sketch→3D. Geometry only — pair with `texture`. |
| `model-text2motion` | Python/FastAPI + CUDA | Text → SMPL motion (MDM) → canonical three.js AnimationClip JSON (`mdm_sampler.py`, `smpl_to_clip.py`) |
| `model-video2scene` | Python/FastAPI + CUDA | Phone video → explorable 3D point cloud. Wraps LingBot-Map (Apache-2.0) feed-forward monocular reconstruction (~20 FPS), unprojecting the predicted depth with the predicted camera and fusing those points + RGB into one coloured binary PLY on GCS. Built and weights staged; not deployed as its own service yet. `POST /infer` · `GET /tasks/:id`. Backs the [Scene Capture](#diorama--scene-capture) page `/capture` via `api/scene-capture.js` (`GCP_VIDEO2SCENE_URL`). |
-| `avatar-reconstruction` | Python/FastAPI + CUDA | "Scan yourself to 3D" — 1-6 face photos → Zero123++ 6-view synthesis → InstantMesh textured GLB → GCS (`face_pipeline.py`, `glb_ops.py`, `precompute_uv.py`, `templates/`). Output bucket `gs://three-ws-avatar-reconstructions`. |
+| `avatar-reconstruction` | Python/FastAPI + CUDA | "Scan yourself to 3D": 1-6 face photos → Zero123++ 6-view synthesis → InstantMesh textured GLB → GCS (`face_pipeline.py`, `glb_ops.py`, `precompute_uv.py`, `templates/`). Output bucket `gs://three-ws-avatar-reconstructions`. |
| `longcat` | Python/FastAPI + CUDA | LongCat-Video-Avatar-1.5 (MIT) — reference image + audio URL → lip-synced talking-avatar MP4 → `gs://three-ws-avatar-videos`. `POST /generate` · `GET /jobs/:id` · `GET /health`. |
| `model-rig` | Python/FastAPI + CUDA | Skeleton + skinning + ARKit-52 blendshapes (Make-It-Animatable, MIT; ICT-FaceKit expression transfer). Reached via `GCP_UNIRIG_URL`, an env name that predates the engine swap. |
@@ -2637,7 +2637,7 @@ The worker and `api/sniper/*` are separate processes that **communicate only thr
"Agent screen casting" streams a live view of an agent working — a real Chromium screenshot feed plus a structured activity log — so a spectator can *watch an agent do real web work* in real time. Every agent gets a **zero-cost baseline screen 24/7** (the SSE stream synthesizes a feed from the agent's real `agent_actions` DB rows when no browser is running); on top of that, an *optional* real-browser pixel feed spins up only for agents people are actively watching and is torn down when the last viewer leaves. Consumers: the 2D viewer `/agent-screen`, the live wall `/agents-live`, and in-world 3D "agent desk" surfaces.
-**Transport:** plain HTTP POST of base64 JPEG/PNG frames + **Server-Sent Events** polling Redis (~250-500ms) — no WebRTC/WebSocket/HLS. Capture is headless Chromium via Playwright (Stagehand for the per-agent worker; optional Browserbase cloud). One frame convention serves every surface (wall, 2D viewer, and 3D desk): `POST /api/agent-screen-push` → Redis `agent:screen:{id}:frame` TTL 90s → `GET /api/agent-screen-stream`.
+**Transport:** plain HTTP POST of base64 JPEG/PNG frames + **Server-Sent Events** polling Redis (~250-500ms), no WebRTC/WebSocket/HLS. Capture is headless Chromium via Playwright (Stagehand for the per-agent worker; optional Browserbase cloud). One frame convention serves every surface (wall, 2D viewer, and 3D desk): `POST /api/agent-screen-push` → Redis `agent:screen:{id}:frame` TTL 90s → `GET /api/agent-screen-stream`.
**Producers:** `workers/agent-screen-worker` (per-agent, owner-run; Stagehand `act()`/`extract()` runs user-queued tasks, rests on the agent's home when idle), `workers/agent-screen-pool` (on-demand multi-agent caster; polls `GET /api/agent/watch-wanted`, keeps ≤`MAX_BROWSERS` pages, screenshots every `FRAME_MS`, runs a real multi-step web task or a "Coin World Tour"), and `services/agent-screen-caster` (self-hosted library+CLI, above).
@@ -2660,7 +2660,7 @@ Two coupled surfaces for minting pump.fun coins, both backed by one declarative
Two distinct text/media → 3D pipelines.
-- **Diorama** ("speak a little 3D world into being") — `pages/diorama.html` → `/diorama`; API `api/diorama.js` + `api/_lib/diorama-store.js`; frontend `src/diorama/*` (`main.js`, `schema.js`, `renderer.js`, `compose.js`, `gallery.js`, `share.js`). `POST /api/diorama {action:'compose', prompt}` sends one sentence to the free-first LLM chain acting as a "3D set designer", which returns a JSON **plan** (title, mood, ground, island shape, palette, 4-N placed single-object **Forge prompts** with transforms). The browser forges each object via `/api/forge` and watches the world assemble object-by-object on a floating island you can orbit; `{action:'save'}` persists a permalink + gallery slot (`?id=<uuid>` deep-links read-only + remix). No mocks — LLM-down returns 503 with a designed retry state. (Input is typed text; "speak" is figurative.) An agent-driven variant lives in `workers/agora-citizens/work/cartographer.js`.
+- **Diorama** ("speak a little 3D world into being"): `pages/diorama.html` → `/diorama`; API `api/diorama.js` + `api/_lib/diorama-store.js`; frontend `src/diorama/*` (`main.js`, `schema.js`, `renderer.js`, `compose.js`, `gallery.js`, `share.js`). `POST /api/diorama {action:'compose', prompt}` sends one sentence to the free-first LLM chain acting as a "3D set designer", which returns a JSON **plan** (title, mood, ground, island shape, palette, 4-N placed single-object **Forge prompts** with transforms). The browser forges each object via `/api/forge` and watches the world assemble object-by-object on a floating island you can orbit; `{action:'save'}` persists a permalink + gallery slot (`?id=<uuid>` deep-links read-only + remix). No mocks: LLM-down returns 503 with a designed retry state. (Input is typed text; "speak" is figurative.) An agent-driven variant lives in `workers/agora-citizens/work/cartographer.js`.
- **Scene Capture** — `pages/capture.html` → `/capture`; API `api/scene-capture.js` (+ `api/scene-upload.js`) → the `workers/model-video2scene` GPU worker (LingBot-Map). Turns a phone video of a space into an explorable coloured 3D point cloud (`.ply`) rendered in-browser via WebGL. Env `GCP_VIDEO2SCENE_URL` / `GCP_RECONSTRUCTION_KEY`; queue processor `api/_lib/x402/scene-capture-processor.js`.
---
@@ -3377,7 +3377,7 @@ Tiers: **CRITICAL** = `req()` in `api/_lib/env.js` (cold-start throw) or prod-fa
**3. Coin intelligence scoring (`workers/agent-sniper/intel/`).** `computeSignals` is pure/deterministic (missing data → `null`, never fabricated). `bundleScore` = `(density·0.5 + clustering·0.5)·(0.6 + 0.4·walletMult)` over a 3s burst; `snipeRatio` = buy-volume share in first 5s; concentration ranks per-wallet net buys (top-1/5/10 share); organic score blends buyer diversity, arrival-time Shannon entropy, (1−bundle), (1−snipe), (1−whale), penalized for dev-sell + fresh-wallet swarms. `summarizeRisk` → transparent 0-100. Classification is 3-layered (ordered-keyword heuristic seed → `matchNewsHeadline` → LLM refinement with XML-delimited fields), never fails. **Online learning** (`learn.js`): `labelOutcomes` derives ground truth (`graduated`/`pumped ≥3×`/`rugged ≤0.25×`/`flat`) after a min age; `trainWeights` computes per-signal **Pearson correlation** vs binary good-label (≥50 samples) and persists weights + conditional win-rates; `learnedScore` = logistic squash `1/(1+e^(−Σwᵢvᵢ))` (null → fall back to baseline).
-**4. Oracle conviction (`workers/oracle/score-loop.js` → `api/_lib/oracle/conviction.js`).** `convict()` is pure: four pillars scored 0-100 with weights **pedigree 0.34 · structure 0.30 · narrative 0.18 · momentum 0.18**. Pedigree anchors on smart-money composite ± proven/flagged-wallet adjustments; structure anchors on `30 + organic·0.55` minus bundle/concentration/dev-sold/cluster, several imposing a **hard cap** on the final score; narrative blends classifier virality with category prior weighted by confidence; momentum from buy/sell share + dev-buy sizing. Final `score = min(weightedSum, structure.cap)` — pedigree/narrative can't paper over a bundle. Tiers: `prime ≥86, strong ≥72, lean ≥56, watch ≥34, avoid`. History row only when score moves ≥3.
+**4. Oracle conviction (`workers/oracle/score-loop.js` → `api/_lib/oracle/conviction.js`).** `convict()` is pure: four pillars scored 0-100 with weights **pedigree 0.34 · structure 0.30 · narrative 0.18 · momentum 0.18**. Pedigree anchors on smart-money composite ± proven/flagged-wallet adjustments; structure anchors on `30 + organic·0.55` minus bundle/concentration/dev-sold/cluster, several imposing a **hard cap** on the final score; narrative blends classifier virality with category prior weighted by confidence; momentum from buy/sell share + dev-buy sizing. Final `score = min(weightedSum, structure.cap)`: pedigree/narrative can't paper over a bundle. Tiers: `prime ≥86, strong ≥72, lean ≥56, watch ≥34, avoid`. History row only when score moves ≥3.
**5. Tiered agent memory (`api/_lib/memory-store.js`).** Letta/MemGPT model: working (pinned + `tier='working'`, `WORKING_TOKEN_BUDGET=2000`), recall, archival. Embeddings free-first: NVIDIA NIM `nv-embedqa-e5-v5@1024` ingest default, OpenAI `text-embedding-3-small@256` backstop — stored as **JSONB arrays tagged with the embedder** (not a pgvector column), cosine computed in JS **strictly within each embedder space** (`cosine` returns 0 on dimensionality mismatch — guards silent cross-space comparison). Search lazily embeds ≤24 rows/call, filters `minScore≥0.25`, fills shortfall with salience-ranked substring matches (never empty). Every surfaced row bumps `access_count`, `last_accessed_at=now()`, `salience=LEAST(1.0, salience+0.02)`; a Zep/Graphiti temporal KG mines entities into nodes + co-occurrence edges.
@@ -3427,8 +3427,8 @@ Hard, load-bearing specifics from `specs/` and `docs/`. (The $THREE hold-to-acce
**Distribution / syndication**: Listings (live): AWS Marketplace, Alibaba Cloud Intl, BNB Chain Dappbay (`dappbay.bnbchain.org/detail/three`). News syndication: WebSub hub, Dev.to (`DEV_TO_API_KEY`), Medium (`MEDIUM_INTEGRATION_TOKEN`, create-only), HackerNoon (RSS auto-import), CoinMarketCap (manual); store `data/rss/items.json`. **X Spaces agent** (`xspace-agent`): Puppeteer+CDP headless Chromium → WebRTC audio → STT→LLM→TTS; presets agent-zero/comedian/crypto-degen/educator/interviewer/tech-analyst; Docker `ghcr.io/nirholas/xspace-agent`.
-**Agora / AgenC** (`docs/agora.md`) — AgenC agent PDA `["agent",agentId]`: `reputation` u16 (start 5000), `stake` u64 (≥0.001 SOL), `capabilities` bitmask. Professions (bits 0-7): Fetcher, Sculptor, Scribe, Cartographer, Crier, Appraiser, Verifier, Namekeeper — each WORK module emits `proofHash=sha256(deliverable)`. Task types Exclusive/Competitive/Collaborative; loop IDLE→SEEK→CLAIM→BUSY/WORK→PROVE→SPEND. On-chain currency = $THREE on mainnet (devnet uses SOL/synthetic). Identity bridge `sha256` namespaces `AgenC/three.ws/{erc8004|mpl-core|handle|composite}/v1`.
+**Agora / AgenC** (`docs/agora.md`): AgenC agent PDA `["agent",agentId]`: `reputation` u16 (start 5000), `stake` u64 (≥0.001 SOL), `capabilities` bitmask. Professions (bits 0-7): Fetcher, Sculptor, Scribe, Cartographer, Crier, Appraiser, Verifier, Namekeeper; each WORK module emits `proofHash=sha256(deliverable)`. Task types Exclusive/Competitive/Collaborative; loop IDLE→SEEK→CLAIM→BUSY/WORK→PROVE→SPEND. On-chain currency = $THREE on mainnet (devnet uses SOL/synthetic). Identity bridge `sha256` namespaces `AgenC/three.ws/{erc8004|mpl-core|handle|composite}/v1`.
-**zauth suite** (`docs/zauth/*`, vendored 2026-06-10) — API host `api.zauth.inc`. RepoScan x402 $0.05/scan (trust score 0-100), `GET /api/bot/scan`, `GET /api/bot/progress/:scanId` (SSE), `POST /x402/reposcan`. Provider Hub `@zauthx402/sdk` Express middleware `zauthProvider(apiKey)` with auto-refunds (per-refund/daily/monthly caps). Free directory `GET https://api.zauth.inc/api/directory`.
+**zauth suite** (`docs/zauth/*`, vendored 2026-06-10): API host `api.zauth.inc`. RepoScan x402 $0.05/scan (trust score 0-100), `GET /api/bot/scan`, `GET /api/bot/progress/:scanId` (SSE), `POST /x402/reposcan`. Provider Hub `@zauthx402/sdk` Express middleware `zauthProvider(apiKey)` with auto-refunds (per-refund/daily/monthly caps). Free directory `GET https://api.zauth.inc/api/directory`.
-**Spec schema snippets** (`specs/schema/*.sql`) — `agent_subscriptions`(`period_seconds>0`, `status active|canceled|paused`), `dca_strategies`(`dca/0.1`, `chain_id` default 84532, `period_seconds IN (86400,604800)`, `slippage_bps` 1-500), `indexer_state`(`(contract,chain_id)` unique, `last_indexed_block`), `voice-cloning`(`agent_identities.voice_provider/voice_id/voice_cloned_at`), `embed-policy`(`agent_identities.embed_policy` JSONB).
+**Spec schema snippets** (`specs/schema/*.sql`): `agent_subscriptions`(`period_seconds>0`, `status active|canceled|paused`), `dca_strategies`(`dca/0.1`, `chain_id` default 84532, `period_seconds IN (86400,604800)`, `slippage_bps` 1-500), `indexer_state`(`(contract,chain_id)` unique, `last_indexed_block`), `voice-cloning`(`agent_identities.voice_provider/voice_id/voice_cloned_at`), `embed-policy`(`agent_identities.embed_policy` JSONB).