# Introduction

> Autonomous AI for game NPCs

Architect the next generation of **Synthetic Life**. ForbocAI is the proprietary substrate for embedding autonomous consciousness into your digital worlds.

## The Architecture

<div>
  Systém_Óverview // Prótocol_Init
</div>

<div>
  ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ
</div>

ForbocAI is not a chatbot wrapper. It is a **Neuro-Symbolic Intelligence Protocol** that gives you god-like control over your agents.

### 🚫 The No-Class Manifesto

We **reject** Object-Oriented Programming (OOP) classes (`class`) in favor of **Functional Composition**.

* **State is Immutable**: Objects are never mutated via `this`. New versions are returned.
* **Pure Functions**: Logic is separated from data.
* **Factory Pattern**: We use factory functions (`createAgent`) with closures to encapsulate private state.

### 🏛️ The Architecture

The **ForbocAI Protocol** strictly separates **State** from **Logic**:

1. **SDK (The Vessel)**: Self-contained container for the Agent's existence.
   * **SLM Cortex**: Local inference engine (no cloud dependency).
   * **Vector Memory**: Local database (browser/fs) for persistent memory.
   * **Self-Contained**: Can run headless without any external requirements except the API connection.
2. **API (The Truth)**: Stateless validation oracle.
   * **No Database**: The API stores nothing. It is pure logic.
   * **The Grid**: Enforces the laws of physics/game rules via pure functions.

> *You don't just script NPCs. You birth them.*

## Core Components

<div>
  Módulátion_Máp // Sýstem_Óverview
</div>

<CardGroup cols={2}>
  <Card title="Cortex" icon="duotone brain" href="/concepts/cortex">
    Local-first SLM inference engine for NPC AI
  </Card>

  <Card title="Bridge" icon="duotone bridge" href="/concepts/bridge">
    Neuro-symbolic state validation layer
  </Card>

  <Card title="Memory" icon="duotone database" href="/concepts/memory">
    RAG pipeline for persistent agent memory
  </Card>

  <Card title="Soul" icon="duotone ghost" href="/concepts/soul">
    Portable agent identity and state serialization
  </Card>
</CardGroup>

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

## Quick Start

<div>
  Quíck_Stárt // Instáll_Séquence
</div>

<Steps>
  <Step title="Install the SDK">
    ```bash
    npm install forbocai
    ```
  </Step>

  <Step title="Verify Connection">
    Run the CLI to verify your connection to the Neuro-Symbolic Grid:

    ```bash
    npx forbocai api status
    ```
  </Step>

  <Step title="Initialize the Cortex">
    **Functional Init**: Use `createCortex` factory, not classes.

    ```typescript
    import { createCortex } from 'forbocai';

    const cortex = createCortex({
      model: 'smollm2-135m'
    });
    await cortex.init();
    ```
  </Step>

  <Step title="Create an Agent">
    ```typescript
    import { createAgent } from 'forbocai';

    const agent = createAgent({
      cortex,
      persona: `You are Kira, a cautious merchant in a dystopian market.
                You distrust strangers but can be won over with fair trades.`,
      initialState: {
        inventory: ['rusty_key', 'healing_potion'],
        mood: 'suspicious'
      }
    });
    ```
  </Step>

  <Step title="Interact with the Agent">
    ```typescript
    const response = await agent.process({
      input: "I'd like to buy that key from you.",
      context: { playerGold: 50 }
    });

    // response.dialogue: "That key? It's... special. 50 gold and we have a deal."
    // response.action: { type: 'OFFER_TRADE', item: 'rusty_key', price: 50 }
    ```
  </Step>
</Steps>

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

## CLI Toolkit

<div>
  Tóol_Kít // Cónsole
</div>

The SDK includes a built-in CLI for interacting with the Neuro-Symbolic Grid directly.

```bash
# Check connection to the Grid
npx forbocai api status

# Create a test agent
npx forbocai agent create "Cyberpunk Merchant"

# Export an agent's Soul to IPFS
npx forbocai soul export <agent-id>

# Import an agent from a Soul (CID)
npx forbocai soul import <cid>
```

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

## Development Cycle

<div>
  Tést_Séquence // Válidátion
</div>

For contributors and advanced integrators, the validation loop ensures stability across the Split-Brain architecture.

<Steps>
  <Step title="Local Updates">
    Make changes to the `sdk/` or `api/` codebase.
  </Step>

  <Step title="Deploy">
    * **SDK**: Push to NPM (`npm publish`)
    * **API**: Push to GitHub (Triggers Render auto-deploy)
  </Step>

  <Step title="Consume">
    Install the latest version in your client application:

    ```bash
    npm install forbocai@latest
    ```
  </Step>

  <Step title="Verify">
    Validate the end-to-end connection using the CLI:

    ```bash
    npx forbocai api status
    # > Connecting to Neuro-Symbolic Grid...
    # > Status: ONLINE
    ```
  </Step>
</Steps>

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

## Documentation

<div>
  Dócs_Máp // Référence
</div>

<CardGroup cols={2}>
  <Card title="User Stories" icon="duotone book-open" href="/user-stories">
    What developers can build with the SDK
  </Card>

  <Card title="API Reference" icon="duotone code" href="/api-reference">
    Complete endpoint documentation
  </Card>

  <Card title="Concepts" icon="duotone lightbulb" href="/concepts">
    Architecture and design patterns
  </Card>

  <Card title="Examples" icon="duotone flask" href="/examples">
    Sample implementations and tutorials
  </Card>
</CardGroup>