ForbocAI API Overview

API_Óvervíew // Scópe_&_Cádence

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

Scope, Audience, and Cadence

• Scope: The API provides the cloud-based logic layer and the neuro-symbolic orchestration that drives the local SDK. It enforces deterministic rules, constructs directives, validates actions against a protocol contract, and coordinates between the local SDK (Vector DB, SLM, memory) and the game engine. The API is the private, central authority for the “Mind” in the Split-Brain architecture.
• Audience: You (the project owner) and any future private contributors integrating the API with the SDK and the game client. This document is a reference for how the API is intended to behave and how it interfaces with the SDK and the engine.
• Cadence: This is a living document. Major architectural shifts and protocol changes should be reflected in the API overview; minor improvements can be reflected in a lightweight revision. A simple cadence is to review every release and quarterly for longer‑term architectural changes.

Glossary and Key Terms

• Cortex: The local reasoning/generation brain exposed by the SDK in the client; the API provides rationale and directives that Cortex uses to drive the agent.
• Memory: The local vector store maintained by the SDK. It stores observations, embeddings, and memories to support retrieval and context during decision making.
• SLM: The local language model runtime used by the SDK for generation tasks.
• Vector DB: Local vector database (e.g., Orama) used to index and fetch contextual embeddings.
• Observation: A structured input representing a game event or state observation to be consumed by the API (and stored in Memory).
• Directive: The system prompt or constraints produced by the API that guide the SDK’s generation/acting process.
• AgentAction: The concrete action the SDK asks the engine to execute (e.g., MOVE, ATTACK, INTERACT, SPEAK).
• ProtocolAction: The canonical JSON action defined by the protocol that the API uses to instruct the SDK. This is the wire format that is exchanged between the SDK and the API.
• Soul: A digital representation of an agent’s long‑term identity/assets; used in the soul/agent economy flow.
• Ghost: A headless/automated QA or test agent used for playtesting and validation.
• Endpoints: The REST/NHTTP surface exposed by the API (e.g., /cortex/models, /agents, /agents/{id}/process, /bridge/validate, /agents/{id}/soul/export).
• OpenAPI/Fern: The API surface contract and code generation guidance that defines request/response schemas.
• Context: The current world/context fed into the API for reasoning (Observation + State + Memory).
• Protocol: The contract that binds between the API and the SDK (types and schemas for Observation, Directive, and Action).

Architecture Diagrams

Three-layer diagram (ASCII):

+---------------+        +-------------------+        +-----------------+
|  Game Engine  | ---> |  SDK (Container)  | ---> |  API (Mind)     |
|   (Forboc)     |       |  Vector DB, SLM,  |       |  Rule Engine,   |
|                 | <--- |  Memory, State    | <--- |  Directive Gen   |
+---------------+        +-------------------+        +-----------------+
        ^                       ^                          ^
        | Observations/Actions  | Protocol/Requests        | Directive/Actions
        |                       |                          |
        +---------------------------------------------------------+
                                 Data Flow

Versioning and Compatibility Policy

• Versioning model: Semantic versioning for API and SDK (MAJOR.MINOR.PATCH).
• Compatibility policy:
  • API and SDK maintain backward compatibility within the same major version unless a breaking change is required.
  • Breaking changes trigger a new major version with migration guidance and a deprecation window.
• Upgrade path: Provide a deprecation timeline (minimum 90 days) for breaking changes.
• Changelog: Maintain a central changelog latent in the repo (or a shared docs location) that lists API/SDK changes per release.

Onboarding and Contribution Guidelines

• Private project: No external contributors by default; treat this as a personal private dev loop.
• Local onboarding steps:
  1. Install API and SDK dependencies in their respective repos.
  2. Run the API locally and verify endpoints via curl or a small REST client.
  3. Point the game client at the local API (environment variable or config tweak).
  4. Run a simple end-to-end test: create an Observation, invoke /agents/{id}/process, and confirm an AgentAction is produced and can be acted on by the engine.
  5. Validate the end-to-end loop by hand‑driving a sample scenario (observation -> directive -> action -> in‑game effect).
• Contribution guidelines (for private project):
  • All changes go through your private repo and are versioned with a meaningful commit message.
  • Document any breaking changes with migration notes.
  • Ensure all changes have test coverage in the respective SDK/API test suites.

Canonical Data Models and Protocol Definitions

• Place protocol contracts in a shared location (sdk/src/core/index.ts) with:
  • Observation
  • Directive
  • AgentAction
  • ProtocolAction

Example TypeScript interfaces (shared location):

export interface Observation {
  id: string;
  timestamp: string; // ISO 8601
  event: string;
  payload?: any;
}

export interface Directive {
  id: string;
  systemPrompt: string;
  constraints: string[];
}

export type AgentAction =
  | { type: 'MOVE'; x: number; y: number }
  | { type: 'ATTACK'; targetId: string }
  | { type: 'INTERACT'; objectId: string }
  | { type: 'SPEAK'; text: string };

export interface ProtocolAction {
  type: 'MOVE' | 'ATTACK' | 'INTERACT' | 'SPEAK' | 'IDLE';
  payload?: any;
}

• The API should reference these types in its input/output envelopes and the SDK should implement these types for compatibility.
• Both api/ and Forboc client docs should reference the canonical location for these contracts.

Cross‑repo Doc Map

Onboarding Guide (End-to-end Local Dev Loop)

1. Prerequisites: Node.js, a package manager (pnpm/yarn/npm), and access to the private repos.
2. API: In api/hs, install dependencies and run the API locally.
   • Commands: cabal update, cabal build, cabal run
3. SDK: In sdk, install dependencies and build.
   • Commands: npm install or pnpm install, npm run build or pnpm run build
4. Game client: In Forboc/client, install dependencies and point to the local API base URL.
   • Update config to API_BASE_URL=http://localhost:port
5. Verification loop:
   • Send a sample Observation to the API (curl or test client) and verify a Directive is returned.
   • Let the SDK generate an AgentAction and verify the action is executed by the game engine.
   • Confirm end-to-end flow by reproducing a small scenario.

Source of Truth for Versioning and Compatibility

• A single versioning policy should govern both API and SDK with a cross‑repo version matrix.
• All repos should cite the canonical definitions located in sdk/src/core/index.ts.
• The glossary should include the terms defined above with exact wording to prevent drift across api/client docs.
• Cross-link to a single source of truth for the protocol contracts and data models.

This file represents the canonical overview for the API in this private project. Update this overview whenever you introduce changes to the protocol contract, data models, or API surface.