# Concepts

> Architecture and core abstractions of the ForbocAI SDK

`Cóncépts // Sýstém_Dóc`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

This document explains the core concepts and architecture of the ForbocAI SDK. Understanding these abstractions will help you design effective AI-powered NPCs for your games.

***

## Architecture Overview

<div>
  Archítect_Init // Boot_Séquence
</div>

```
┌─────────────────────────────────────────────────────────────┐
│                       Your Game                             │
├─────────────────────────────────────────────────────────────┤
│                      ForbocAI SDK                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Agent   │  │  Memory  │  │  Bridge  │  │   Soul   │    │
│  │          │◄─┤  (RAG)   │  │ (Neuro-  │  │ (Export/ │    │
│  │ Persona  │  │          │  │ Symbolic)│  │  Import) │    │
│  └────┬─────┘  └──────────┘  └────┬─────┘  └──────────┘    │
│       │                           │                          │
│       ▼                           ▼                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                      Cortex                           │   │
│  │           (Local SLM Inference Engine)                │   │
│  └──────────────────────────────────────────────────────┘   │
31: ├─────────────────────────────────────────────────────────────┤
│     Developer Runtime   │   Storage   │  IPFS Gateway       │
└─────────────────────────────────────────────────────────────┘
```

***

## Cortex

<div>
  Córtex_Init // Locál_Inférence_V.02
</div>

<div>
  ᚠ ᛫ ᚢ ᛫ ᚦ ᛫ ᚨ ᛫ ᚱ ᛫ ᚲ
</div>

The **Cortex** is the local-first inference engine. It runs quantized Small Language Models (SLMs) in your environment—no external API required.

### Key Properties

* **Zero Latency** — No network round-trips; inference happens on-device
* **Zero Cost** — No API token fees; users provide their own compute
* **Privacy-First** — Prompts and responses never leave the device
* **Offline-Capable** — Works without internet after initial model download

### Model Selection

The Cortex supports multiple quantized models. Smaller models are faster but less capable:

| Model          | Parameters | Download Size | Use Case                     |
| -------------- | ---------- | ------------- | ---------------------------- |
| `smollm2-135m` | 135M       | \~100MB       | Fast responses, simple tasks |
| `smollm2-360m` | 360M       | \~250MB       | Balanced performance         |
| `llama3-8b-q4` | 8B (Q4)    | \~4GB         | Complex reasoning            |

***

## Agent

<div>
  Agént_Entíty // Autónomous_Únit
</div>

<div>
  ᛭ ᚠ ᛫ ᚨ ᛫ ᛁ ᛭
</div>

An **Agent** is an autonomous entity with a persona, state, and memory. Agents process inputs and produce structured outputs (dialogue + actions).

### Agent Lifecycle

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CREATE    │────▶│   ACTIVE    │────▶│  EXPORTED   │
│  (Persona)  │     │ (Processing)│     │   (Soul)    │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       │                   ▼                   │
       │            ┌─────────────┐            │
       └───────────▶│  IMPORTED   │◀───────────┘
                    │ (from Soul) │
                    └─────────────┘
```

### Agent State

An agent maintains internal state that influences its behavior:

```typescript
interface AgentState {
  // Core attributes
  inventory: string[];
  skills: Record<string, number>;
  relationships: Record<string, number>;  // -100 to 100
  
  // Emotional state (influences dialogue tone)
  mood: 'hostile' | 'suspicious' | 'neutral' | 'friendly' | 'loyal';
  fear: number;      // 0-100
  confidence: number; // 0-100
  
  // Custom attributes (application-specific)
  [key: string]: unknown;
}
```

### Processing Flow

When `agent.process()` is called:

1. **Recall** — Relevant memories are retrieved via semantic search
2. **Prompt** — System prompt + persona + memories + context + input are assembled
3. **Generate** — Cortex generates a structured response (dialogue + action)
4. **Validate** — Bridge validates the action against application rules
5. **Update** — Agent state is updated based on the interaction
6. **Store** — The interaction is stored as a new memory

***

## Memory (RAG Pipeline)

<div>
  Mémory_Córe // Sémantiç_Récall
</div>

<div>
  ᛊ ᛫ ᛟ ᛫ ᚢ ᛫ ᛚ
</div>

The **Memory** system provides persistent, semantic recall for agents. It uses Retrieval-Augmented Generation (RAG) to inject relevant past events into the agent's context.

### How It Works

1. **Observe** — Events are converted to natural language descriptions
2. **Embed** — Text is converted to vectors using a local embedding model
3. **Store** — Vectors are persisted in IndexedDB
4. **Recall** — Semantic search finds relevant memories before generation

### Memory Types

| Type          | Description          | Example                                   |
| ------------- | -------------------- | ----------------------------------------- |
| `observation` | Witnessed events     | "The player attacked me"                  |
| `experience`  | First-person actions | "I traded the key for gold"               |
| `knowledge`   | Learned facts        | "The player's name is Alex"               |
| `emotion`     | Emotional reactions  | "I felt betrayed when they stole from me" |

### Memory Decay (Optional)

Memories can be configured to decay over time or with distance:

```typescript
const agent = await Agent.create({
  memoryConfig: {
    decay: 'temporal',       // 'none' | 'temporal' | 'importance'
    decayRate: 0.01,         // Relevance reduces by 1%/day
    maxMemories: 1000        // Oldest memories pruned when exceeded
  }
});
```

***

## Bridge (Neuro-Symbolic Validation)

<div>
  Brídge_Protócol // Válidátion_Láyer
</div>

<div>
  ᛒ ᛫ ᚱ ᛫ ᛁ ᛫ ᛗ
</div>

The **Bridge** ensures AI-generated actions are valid within your application's rules. It prevents hallucinations from breaking game state.

### The Problem

LLMs can generate *anything*, including impossible actions:

```json
{ "action": "EQUIP", "item": "legendary_sword" }
// But the agent doesn't have a legendary_sword!
```

### The Solution

The Bridge validates actions before execution:

```typescript
const bridge = new Bridge({
  rules: [
    // Built-in rule: can only equip owned items
    Bridge.rules.requireOwnership('EQUIP', 'inventory'),
    
    // Custom rule: no trading during combat
    (action, context) => {
      if (action.type === 'TRADE' && context.inCombat) {
        return { valid: false, reason: 'INVALID_DURING_COMBAT' };
      }
      return { valid: true };
    }
  ]
});
```

### Validation Flow

```
┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│   SLM   │────▶│ Parse   │────▶│ Bridge  │────▶│ Execute │
│ Output  │     │ Action  │     │ Validate│     │ or      │
│         │     │         │     │         │     │ Reject  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
```

***

## Soul

<div>
  Sóul_Expórt // Portáble_Státe
</div>

<div>
  ᛊ ᛫ ᛟ ᛫ ᚢ ᛫ ᛚ
</div>

A **Soul** is a portable snapshot of an agent's complete being—its persona, memories, and state. Souls enable agents to persist across sessions or transfer between applications.

### Soul Schema

```typescript
interface Soul {
  // Identity
  id: string;
  version: string;
  createdAt: string;
  
  // Persona
  persona: string;
  baseModelWeights?: string;  // Optional LoRA CID
  
  // Memory
  memories: Array<{
    text: string;
    embedding: number[];
    timestamp: string;
    type: string;
  }>;
  
  // State
  state: AgentState;
  
  // Provenance (for verification)
  signature?: string;
  trainingProof?: string;  // ERC-7007 verification
}
```

### Storage Options

| Storage    | Description            | Use Case                        |
| ---------- | ---------------------- | ------------------------------- |
| Local JSON | Export to file         | Development, debugging          |
| IndexedDB  | local persistence      | Session continuity              |
| IPFS       | Decentralized storage  | Cross-app portability, trading  |
| On-chain   | Metaplex Core (Solana) | Verified ownership, marketplace |

***

## Economy & Protocol (Solana)

<div>
  Web3_Láyer // $FAI_Tóken
</div>

<div>
  ᛋ ᛫ ᛟ ᛫ ᛚ ᛫ ᚨ ᛫ ᚾ ᛫ ᚨ
</div>

The ForbocAI Protocol is built on **Solana** to enable a high-frequency, low-latency Asset Economy.

### The \$FAI Token

**\$FAI** is the unified utility token for the entire ecosystem.

* **Network**: Solana (SPL Token)
* **Contract**: `7zwfQkkPv9aUF6VXA8CbZabJYpXCRJTYbQnjxjynpump`
* **Utility**:
  1. **Minting Souls**: Spending \$FAI to "birth" new agent NFTs.
  2. **Inference Credits**: Spending \$FAI to buy API credits for the Cloud Brain (Logic Engine).
  3. **Marketplace**: The base currency for trading high-value Agents.

### Metaplex Core (The Asset Standard)

We use **Metaplex Core** instead of legacy standards (like ERC-721) because it is designed for *Applications*, not just Art.

* **Low Cost**: Minting and updating assets costs fractions of a penny.
* **Dynamic Data**: Core assets have efficient plugin systems that allow us to update the "Memory Hash" of an agent frequently without incurring high gas fees.
* **Zero Copy**: The asset handles are lightweight, enabling games to check ownership of thousands of agents instantly.

***

## Ghost Agents

<div>
  Ghóst_Móde // Héadless_QA
</div>

<div>
  ᛇ ᛫ ᛆ ᛫ ᛟ ᛫ ᛊ ᛫ ᛏ
</div>

**Ghost Agents** are headless AI instances that autonomously test your application. They run at accelerated speed to validate content, find bugs, and collect metrics.

### Capabilities

* **Exploration** — Traverse levels to measure coverage and find dead-ends
* **Dialogue Testing** — Exercise conversation trees to find broken paths
* **Balance Metrics** — Collect time-to-kill, death rates, resource curves
* **Regression Detection** — Compare runs across builds to catch regressions

### Example Usage

```typescript
const results = await GhostAgent.run({
  level: 'dungeon_01',
  goal: 'maximize_exploration',
  timeout: 60_000,
  seed: 12345
});

console.log(results.explorationCoverage);  // 0.94 (94%)
console.log(results.deathCount);           // 2
console.log(results.deadEnds);             // []
```

***

## Learn More

<div>
  Léarn_Móre // FP_Fóundations
</div>

<div>
  ᛭ ᛫ ᛬ ᛫ ᛭
</div>

The ForbocAI SDK is built on functional programming principles. For a deeper understanding of the patterns used in this architecture:

| Topic                  | Lecture                                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Redux Toolkit & FP** | [Redux Toolkit & Functional Programming](https://github.com/seandinwiddie/lectures/blob/main/redux-toolkit-%26-functional-programming/index.md)         |
| **Monads**             | [Monads in Functional Programming](https://github.com/seandinwiddie/lectures/blob/main/monads-in-functional-programming/index.md)                       |
| **Composition**        | [Functional Composition](https://github.com/seandinwiddie/lectures/blob/main/functional-composition/index.md)                                           |
| **FP Maintenance**     | [Functional Programming Maintenance Strategy](https://github.com/seandinwiddie/lectures/blob/main/functional-programming-maintenance-strategy/index.md) |
| **Full Curriculum**    | [Functional Programming Lectures Index](https://github.com/seandinwiddie/lectures/blob/main/index.md)                                                   |