ForbocAI SDK & API Master Checklist

Tódó // Sýstém_Dóc

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

This document serves as the master checklist for building the ForbocAI SDK and its supporting API infrastructure. It consolidates the implementation plan with the architectural standards.

References

• Specs: /Users/seandinwiddie/GitHub/forbocai/fern/openapi.yaml (Fern/OpenAPI source of truth)
• Vision: /Users/seandinwiddie/GitHub/forboc.ai (Source of Truth for “How it Works”)
• Flagship Consumer: /Users/seandinwiddie/GitHub/Forboc (The Game Engine)
• Docs: /Users/seandinwiddie/GitHub/forbocai (Fern/OpenAPI source of truth)
• Standards: /Users/seandinwiddie/GitHub/Forboc/notes/ref/standards/technology-maintenance (FP, CQRS, Redux)
• API Service: Haskell Servant at /Users/seandinwiddie/GitHub/api/hs/
• Deployment: Render.com (configured via render.yaml)

/Users/seandinwiddie/GitHub/Forboc/notes/TODOs/system-todo.md /Users/seandinwiddie/GitHub/sdk /Users/seandinwiddie/GitHub/api

System Architecture & Data Flow

Core Philosophy: - ForbocAI (SDK): The Characters’ Brain/Mind - Infrastructure Layer. It acts as a “tiny harddrive” containing the Vector DB, SLM, and API connectors. It does not contain logic; it serves as the local infrastructure that executes the API’s directives. - Game Engine (Host): The World’s Brain/Mind - Execution Layer. It handles physics, state validation, and execution. - ForbocAI API: The Mind/Law - Logic Layer. The API performs the “Thinking” using proprietary deterministic logic (Pure Functions). It orchestrates the SDK but contains NO AI Models.

The Data Flow:

Game (World State) → SDK (Format/Store) → API (Logic/Decide) → SDK (Generate/Validate) → Game (Execute)

1. Game: Reports event via Protocol (e.g., “Player hit Orc”).
2. SDK: Formats event as Observation, syncs to Local Vector DB, forwards to API.
3. API (Cloud): Runs Pure Logic Gates (deterministic rules, NO AI). Determines Intent and constructs Directive (System Prompt + Constraints).
4. SDK (Local):
   • Retrieval: Fetches relevant context from Vector DB.
   • Generation: Uses Local SLM (Cortex) to generate specific content (dialogue/action) based on API’s Directive.
   • Validation: Validates generated action against Protocol schema.
5. SDK: Returns the final structured Action to the Game via Protocol.
6. Game: Executes the validated action within physics constraints.

Key Principle: The API provides the “Law” (logic), the SDK provides the “Voice” (generation), and the Game provides the “Reality” (execution).

Workflow & Standards

1. API-First Development: Features are built safely in the cloud before reaching the client.
   • Flow: User Stories -> BDD Tests (Haskell) -> API Endpoints -> SDK Integration.
   • The API and SDK are built in tandem, but the API leads.
2. No-Database Policy (API):
   • The API is a Pure Logic Engine. It has NO Database. It holds no state.
   • All state is managed by the SDK’s Local Vector DB (Micro-Database) and passed to the API in the Context of every request.
   • The API determines the next state based only on the input context (Pure Function).

Phase 1: SDK Core Development (Client-Side)

Goal: A lightweight, portable client library that defines the Agent interfaces and infrastructure (Vector DB, SLM, API Client). Strict FP & Immutability.

1.1 Architecture & Setup

• Initialize Package Structure
  • Initialize sdk as a Single Repository.
  • Configure eslint-plugin-functional to enforce immutability.
• Core Types Implementation
  • CRITICAL: Port technical types from /sdk/src/core/index.ts (NOT marketing copy from website).
  • Implement Cortex.init(config) using fetch to Haskell API.
  • Implement Agent.process() to handle state transitions.
  • Implement Protocol types: Observation, Directive, AgentAction.

1.2 Module Implementation

Note: Use Factory Pattern or Functional Composition. Avoid heavy Class Inheritance.

• Cortex Module (Inference)
  • Define ICortex interface for text generation and structured output.
  • Implement createCortex(config) factory.
  • Task: Integrate SLM (WebLLM or similar).
  • Implement streamComplete(request) with SSE support. ✅ COMPLETED 2026-02-04
• Agent Module
  • Create createAgent(config) factory.
  • Implement process(agentState, input) -> newAgentState (Pure Transition).
  • Implement fromSoul(cid) (Import from IPFS).
• Memory Module (Local RAG) ✅ COMPLETED 2026-02-03
  • Privacy-First: Local Vector DB with localStorage persistence.
  • Implement store(memoryDb, text) (Pure wrapper).
  • Implement recall(memoryDb, query) (Semantic similarity search).
  • Implement temporal decay for memory importance.
  • Implement API sync for cloud backup.
• Bridge Module (Validation) ✅ COMPLETED 2026-02-03
  • Implement JSON Schema validation for Agent actions.
  • Create validateAction(action, rules) function.
  • Built-in rules: MOVE, ATTACK, INTERACT, SPEAK, Resources.
  • Strict mode for unknown action types.
• Soul Module (IPFS Portability) ✅ COMPLETED 2026-02-03
  • Implement Soul.export(agent) -> Standardized JSON.
  • Implement IPFS Pinning via API.
  • Implement createSoulInstance() factory function.
  • Implement importSoulFromIPFS(cid) -> Hydrate Agent.
  • Implement createAgentFromSoul(cid) -> Create Agent from Soul.
  • Task: Integrate @metaplex-foundation/umi for Solana interactions.
  • Implement Soul.mint(metadata) -> Create Metaplex Core Asset.
  • CLI Feature: Implement soul chat <id> (Wake from Cryo/Interrogate). ✅ COMPLETED 2026-02-05
• Ghost Module (Automated QA) ✅ COMPLETED 2026-02-03
  • Implement createGhost(config) factory function.
  • Implement startGhostSession() -> Start test session.
  • Implement getGhostStatus() -> Get session progress.
  • Implement getGhostResults() -> Get test results with metrics.
  • Implement waitForGhostCompletion() -> Poll until done.
  • Implement stopGhostSession() -> Stop running session. ✅ COMPLETED 2026-02-04
  • Implement getGhostHistory() -> List past sessions. ✅ COMPLETED 2026-02-04
• Soul Module Additions ✅ COMPLETED 2026-02-04
  • Implement getSoulList() -> List exported souls.
• Memory Module Additions ✅ COMPLETED 2026-02-04
  • Implement Memory.clear() -> Full LanceDB cleanup.

Phase 2: API Service (Proprietary Source)

Goal: The Central Logic Engine. The API handles “Thinking” (Pure Functional Logic & State) and orchestrates the SDK. The SDK handles “Generation” (Local Inference & Memory).

Stack: Haskell Servant, deployed to Render

2.1 Service Infrastructure

• Scaffold Haskell Servant Service
  • Define API types from openapi.yaml using servant-openapi3.
  • Implement Pure Functional handlers (no side effects in logic).
  • Use render.yaml for deployment configuration.
• Database: (REMOVED) API is stateless. All persistence is handled client-side via SDK Vector DB.

2.2 Domain Implementation

• Directive Engine (The “Law”)
  • CRITICAL: Implement the Pure Logic Rule Engine (/agents/{id}/process logic).
  • Usage: Input (State + Context) -> Logic Gates -> Output (System Prompt + Constraints).
  • Create library of “Universal Laws” (e.g., Greed, Fear, Loyalty logic).
  • NO AI MODELS IN API - Only deterministic pure functions.
• Cortex Endpoints (/cortex/init)
  • Implement Licensing Check (Validate API Key or $FAI Balance).
  • Track model initialization state per client.
• Agents Endpoints (/agents)
  • Implement POST /agents (Register Agent).
  • Implement POST /agents/{id}/process (Orchestrate Logic -> SDK Directive).
  • Implement GET/DELETE /agents/{id} (Lifecycle management).
  • Implement GET/PATCH /agents/{id}/state (State sync).
• Memory Endpoints (/agents/{id}/memory)
  • Implement POST /agents/{id}/memory (Store observation).
  • Implement GET /agents/{id}/memory (List memories).
  • Implement POST /agents/{id}/memory/recall (Semantic search).
• Bridge Endpoints (/bridge)
  • Implement POST /bridge/validate (Neuro-Symbolic Anti-Cheat).
  • Implement GET/POST /bridge/rules (Validation rules registry).
  • The Protocol: Enforce strictly typed JSON schemas for all game actions.
• Soul Endpoints (/agents/{id}/soul/export, /agents/import, /souls/{cid})
  • Implement POST /agents/{id}/soul/export (Pin to IPFS via Pinata/Helia).
  • Implement POST /agents/import (Create from Soul).
  • Implement GET /souls/{cid} (Resolve IPFS Data to cached JSON).
• Ghost Endpoints (/ghost/run, /ghost/{id}/status, /ghost/{id}/results) ✅ COMPLETED 2026-02-03
  • Implement POST /ghost/run (Start headless test session).
  • Implement GET /ghost/{id}/status (Session status).
  • Implement GET /ghost/{id}/results (Test results with metrics).
  • Implement POST /ghost/{id}/stop (Stop running session). ✅ COMPLETED 2026-02-04
  • Implement GET /ghost/history (List past sessions). ✅ COMPLETED 2026-02-04
• Soul Endpoints Additions ✅ COMPLETED 2026-02-04
  • Implement GET /souls (List exported souls).
• Memory Endpoints Additions ✅ COMPLETED 2026-02-04
  • Implement DELETE /agents/{id}/memory/clear (Clear agent memories).

BDD Test Suite ✅ COMPLETED 2026-02-03

• Status: Complete feature files and Haskell step definitions
• Feature Files (api/tests/bdd/features/):
  • cortex.feature - Cortex initialization and inference scenarios
  • agents.feature - Agent lifecycle and neuro-symbolic processing
  • memory.feature - Memory storage and semantic recall
  • bridge.feature - Action validation and neuro-symbolic rules
  • soul.feature - IPFS export/import and NFT portability
  • ghost.feature - Automated QA testing sessions and results
• Haskell Step Definitions (api/tests/bdd/hs/Steps/):
  • Cortex.hs - Cortex test steps with HTTP client
  • Ghost.hs - Ghost test steps with session management
• Test Runner: api/tests/bdd/hs/Main.hs
• Cabal Config: api/tests/bdd/forbocai-bdd.cabal
• To run tests: cd api/tests/bdd && cabal run bdd-tests

Documentation ✅ COMPLETED 2026-02-03

• Integration Workflow Documentation
  • Created forbocai/fern/docs/pages/workflow.mdx
  • Documents complete Game → SDK → API → SDK → Game loop
  • Includes Memory and Bridge module usage examples
  • Added to Fern docs navigation