ForbocAI SDK & API Actionable Checklist

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

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

This document serves as the master checklist for building the ForbocAI SDK and its supporting API infrastructure. It is derived from the comprehensive audit and implementation plan.

References

• Specs & Docs: /Users/seandinwiddie/GitHub/forbocai (Fern/OpenAPI source of truth)
• Legacy Monolith: /Users/seandinwiddie/GitHub/Forboc (Source of logic to port)
• Standards: /Users/seandinwiddie/GitHub/Forboc/notes/ref/standards/technology-maintenance (FP, CQRS, Redux)

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

Phase 1: SDK Core Development (Client-Side)

The SDK is a lightweight client that connects to the API. It contains no heavy logic itself but provides the interface for developers.

• 1.1 Initialize Package Structure
  • Create monorepo structure in sdk/
  • Initialize packages/core (Shared types, utils) - Pure Functions Only
  • Initialize packages/client-js (TypeScript SDK)
  • Setup package.json, tsconfig.json, and build scripts
  • Configure eslint and prettier
• 1.2 Core Types & Configuration
  • Port Cortex, Agent, Memory schemas from openapi.yaml to TypeScript interfaces
  • Create ForbocClient base class
  • Implement CortexConfig interface (API URL, License Key)
  • Add license key validation logic in the client constructor
• 1.3 Implement Cortex Module (Inference)
  • Create Cortex class
  • Implement init(config) method - initializes configured inference provider (e.g. Local, Edge, or Cloud)
  • Implement complete(request) method (API wrapper or local inference)
  • Implement streamComplete(request) method (Server-Sent Events handling)
• 1.4 Implement Agent Module
  • Create Agent class
  • Implement create(config) method
  • Implement process(input) method (Dialog + Action loop)
  • Implement fromSoul(cid) (Import from IPFS)
  • Implement state management (getState, updateState)
• 1.5 Implement Memory Module (Local RAG Client)
  • Architecture: Local Micro-Vector DB (e.g., Orama, Voy, or SQLite-vec) embedded in SDK. Privacy-First.
  • Create Memory class attached to Agent instance
  • Implement store(text) method (Pure wrapper around vector insert)
  • Implement recall(query) method (Pure wrapper around vector search)
  • Implement list() method with pagination
• 1.6 Implement Bridge Module (Validation)
  • Create Bridge class
  • Implement validate(action) method
  • Implement registerRule(rule) method for local + remote validation
• 1.7 Implement Soul Module (Portability)
  • Create Soul class
  • Implement export(format) method (JSON/IPFS options)
  • Implement import(cid) static method
• 1.8 Implement Ghost Module (QA)
  • Create GhostAgent class
  • Implement run(config) method to start headless sessions
  • Implement getResults() method for polling metrics

Phase 2: API Service Development (Licensing & Soul Sync)

The API is strictly for Licensing, Analytics, and Soul persistence (IPFS). Real-time memory is local. Architecture must follow CQRS + Event Sourcing.

• 2.1 Service Setup (CQRS/Event Sourcing)
  • Initialize api service (Node.js/Express)
  • Implement Command Bus and Query Bus
  • Implement Event Store (Immutable append-only log)
  • Ensure all Command/Query Handlers are Pure Functions
  • Setup openapi.yaml as source of truth for routing
• 2.2 Database & Storage (Multi-Tenant)
  • Provision PostgreSQL with Nile for native Multi-tenancy
  • Implement Row-Level Security (RLS) for tenant isolation
  • Setup Immutable Migrations (versioned, never modified)
  • Define schemas for Users, Licenses, Events (Memory is NOT central)
  • Configure Connection Pool
• 2.3 Cortex Endpoints (Command/Query)
  • POST /cortex/init - Command: Validate license & Log Access Event
  • POST /cortex/{id}/complete - Command: Relay to Adapter -> Log Token Usage Event
• 2.4 Agent & Soul Endpoints (Command/Query)
  • POST /agents - Command: Register Agent Identity -> Event Store
  • POST /agents/{id}/soul/export - Command: Validate ownership -> Returns IPFS Hash
  • GET /souls/{cid} - Query: Resolve IPFS Gateway url

Phase 3: Licensing & Monetization

The SDK requires a valid license to operate.

• 3.1 License Management
  • Design License Key format (e.g., sk_live_...)
  • Implement generateKey(userId, tier) function
  • Implement Key Verification middleware
• 3.2 Tier Enforcement
  • Define Tiers (Free, Pro, Enterprise)
  • Implement Rate Limiting strategies per tier
  • Implement Model Access Control (e.g., Free = SmolLM2-135M, Pro = Llama-3-8B)

Phase 4: Testing & Release

• SDK Testing
  • Write Unit Tests for all Modules
  • Write Integration Tests using Mock API
• API Testing (Strict TDD/BDD)
  • CRITICAL: NO MOCKING allowed. Tests must run against real DB/EventStore.
  • Write Given-When-Then BDD scenarios for all use cases
  • Write Contract Tests to ensure OpenAPI compliance
  • Write Property-based tests for Pure Functions
• Documentation
  • Generate API Reference from OpenAPI
  • Write “Getting Started” guide
  • Create example project using the SDK
• Release
  • Publish @forbocai/sdk to npm