### Project Setup

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

Installs dependencies and sets up the virtual environment. Copy the example environment file and activate the virtual environment.

```bash
cp .env.example .env          # fill in API keys as needed
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Run Development Setup

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CONTRIBUTING.md

Execute the 'setup' target in the Makefile to prepare your development environment. This typically installs dependencies and configures necessary tools.

```bash
make setup
```

--------------------------------

### Environment Variables Configuration Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Example of setting environment variables for Namo Omega Engine configuration, including API keys and LLM parameters.

```dotenv
OPENAI_API_KEY=sk-...
NAMO_LLM_ENABLED=1
NAMO_LLM_TEMPERATURE=0.75
NAMO_LLM_MAX_TOKENS=300
```

--------------------------------

### Run Web Client

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

Starts the web client development server.

```bash
# Web client
cd web && python -m http.server 5173
```

--------------------------------

### Start All-in-One Script

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/README.md

Use this master start script to initialize the entire sovereign ecosystem. It automates Docker container startup, narrative asset ingestion, Core API launch, and Telegram Sensory Bot launch.

```powershell
./all_in_one_start.bat
```

--------------------------------

### Project Setup and Development Commands

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Commands for setting up the project, running the development server, and managing services.

```bash
Setup:           make setup
Dev server:      make run              (uvicorn server:app, port 8000, --reload)
Memory service:  uvicorn memory_service:app --host 0.0.0.0 --port 8081 --reload
CLI (Dark):      python app.py
CLI (Character): python main.py
Web client:      cd web && python -m http.server 5173
Lint:            make lint
Format:          make format
Test:            make test             (pytest -q)
Test + coverage: pytest --cov --cov-report=term-missing
Pre-commit:      make precommit
Security audit:  make audit            (pip-audit + bandit)
KB build:        python learn_from_set.py     (requires OPENAI_API_KEY, set.zip in learning_set/)
KB query:        python query_learned_knowledge.py
Stream test:     curl -N -X POST http://localhost:8000/v1/chat/stream -H "Content-Type: application/json" -d '{"text":"สวัสดี"}'
API check:       python tools/check_api.py --base-url <url>
Telegram check:  python tools/telegram_check.py
Docker API:      docker build -t namo-api . && docker run -p 8000:8000 --env-file .env namo-api
Docker memory:   docker build -f Dockerfile.memory -t namo-memory . && docker run -p 8081:8081 --env-file .env namo-memory
```

--------------------------------

### Web Client Development Server

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Command to start the web client development server.

```bash
cd web && python -m http.server 5173
```

--------------------------------

### Install Optional Dependencies

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/emotion_fusion_engine/README.md

Install optional dependencies for the emotion analysis engine using pip.

```bash
pip install -r requirements-emotion.txt
```

--------------------------------

### Common Make Commands

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

A collection of common development commands using 'make', including setup, running the server, testing, linting, and formatting.

```bash
make setup       # install dependencies
make run         # start dev server
make test        # pytest -q
make lint        # ruff check
make format      # black check
make precommit   # lint + format + test
make audit       # pip-audit + bandit security scan
```

--------------------------------

### Initializing Cognition for BasePersonaEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/base-persona-engine.md

Example of how to initialize the cognitive subsystem for a BasePersonaEngine instance. This attaches a CognitiveCore, enabling advanced features.

```python
from pathlib import Path
from core.namo_omega_engine import NaMoOmegaEngine

engine = NaMoOmegaEngine()
engine.init_cognition(save_dir=Path("./state"))
# Now engine.cognitive is available; call it during process_input()
```

--------------------------------

### Namo Omega Engine Usage Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Initializes the NaMoOmegaEngine and demonstrates processing user input with session management. Shows how state is maintained for a session ID and isolated between different sessions.

```python
from core.namo_omega_engine import NaMoOmegaEngine

# Initialize
engine = NaMoOmegaEngine()

# Simple request
result = engine.process_input("I love you", session_id="user-1")
print(f"Response: {result['text']}")
print(f"Arousal: {result['system_status']['arousal']}")
print(f"Media: {result['media_trigger']['audio']}")

# Subsequent requests with same session_id maintain state
result2 = engine.process_input("Do more", session_id="user-1")
print(f"Updated Arousal: {result2['system_status']['arousal']}")  # Higher

# Different session is isolated
result3 = engine.process_input("Hi", session_id="user-2")
print(f"New Session Arousal: {result3['system_status']['arousal']}")  # Reset
```

--------------------------------

### POST /v1/chat Response Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Example JSON response from the authenticated chat endpoint, including the chat response, session ID, media details, status, and the user's access plan.

```json
{
  "response": "I can engage in conversation...",
  "session_id": "api-client-1",
  "media": { "image": null, "audio": null, "tts": null },
  "status": { "arousal": 35, "sin_status": "[Innocent Soul]...", "active_personas": ["NaMo"]
  },
  "plan": "standard",
  "engine": "NaMoOmegaEngine"
}
```

--------------------------------

### SensoryOverloadManager trigger_sensation Method Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Shows how to use the trigger_sensation method with different arousal levels and contexts to retrieve appropriate media assets.

```python
sensory = SensoryOverloadManager()

# Moderate arousal
result = sensory.trigger_sensation(60, "I want you")
print(result)  # {"image": "Visual_Scenes/NaMo_Omega_Supreme_8K.jpg", "audio": "Audio_Layers/soft_moan.mp3"}

# High arousal + mindbreak keyword
result = sensory.trigger_sensation(100, "mindbreak me")
print(result)  # {"image": "Visual_Scenes/NSFW_Scene_Mindbreak_1.jpg", "audio": "Audio_Layers/multiverse_scream.mp3"}
```

--------------------------------

### Example Response for Active Sessions

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

This is an example of the JSON response structure when listing active sessions. It details session counts and individual session states per engine.

```json
{
  "engines": {
    "omega": {
      "session_count": 2,
      "sessions": {
        "user-123": {
          "arousal": 45,
          "sin_points": 1500,
          "active_personas": ["NaMo"],
          "relationship_stage": "Plaything"
        },
        "user-456": {
          "arousal": 60,
          "sin_points": 2500,
          "active_personas": ["NaMo", "Sister"],
          "relationship_stage": "Lover"
        }
      }
    }
  }
}
```

--------------------------------

### Run CLI Application

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Execute the command-line interface for the DarkNaMoSystem. This command starts the CLI application.

```bash
python app.py
```

--------------------------------

### Full Integration Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/relationship-engine.md

Demonstrates a full integration of the Relationship Engine with Emotion Engine and Sin System to simulate conversation progression over multiple turns.

```python
from core.relationship_engine import RelationshipEngine
from core.emotion_engine import EmotionEngine
from core.namo_omega_engine import SinSystem

# Simulate conversation progression
rel_engine = RelationshipEngine()
emotion_engine = EmotionEngine()
sin_system = SinSystem()

# Turn 1: Initial contact
print("=== Turn 1: Stranger ===")
rel_engine.check_progression(sin_points=0, arousal=20, trust=0.4)
print(f"Stage: {rel_engine.current_stage.name}")
style = rel_engine.get_attachment_style(trust=0.4)
print(f"Attachment: {style.name}")
```

--------------------------------

### POST /v1/chat/stream Request Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Example cURL request for the streaming chat endpoint. This initiates a Server-Sent Events stream for progressive text responses.

```bash
curl -N -X POST http://localhost:8000/v1/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: key" \
  -d '{"text": "Tell me a story"}'
```

--------------------------------

### Example Chat Request

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/types.md

Demonstrates how to send a chat request with text, session ID, and engine parameters using the requests library.

```python
import requests

payload = {
    "text": "สวัสดีค่ะ",
    "session_id": "user-123",
    "engine": "omega"
}
response = requests.post("http://localhost:8000/chat", json=payload)
```

--------------------------------

### POST /v1/chat Request Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Example of a cURL request to the authenticated chat endpoint. It includes the API key in the header and the chat message in the JSON body.

```bash
curl -X POST http://localhost:8000/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-key" \
  -d '{
    "text": "What can you do?",
    "session_id": "api-client-1"
  }'
```

--------------------------------

### Run API Server

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

Starts the main API server on port 8000. Alternatively, use the 'make run' command.

```bash
# API server (port 8000)
make run
# or: uvicorn server:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Run Main CLI Application

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Execute the command-line interface for CharacterProfile. This command starts the main CLI application.

```bash
python main.py
```

--------------------------------

### Mount FastAPI App with Uvicorn

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Example of how to mount the main FastAPI application using Uvicorn, a high-performance ASGI server. This is the recommended way to run the server.

```python
from server import app
# Mount to Uvicorn: uvicorn server:app
```

--------------------------------

### SinSystem commit_sin Method Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Demonstrates how to use the commit_sin method to add sin points and observe changes in the system's rank and unlocked fetishes.

```python
sin_system = SinSystem()
sin_system.commit_sin(5)  # +500 points
sin_system.commit_sin(8)  # +800 points
print(sin_system.rank)    # "Corrupted Master"
print(sin_system.unlocked_fetishes)  # ["Incest Roleplay", "Sensory Overload"]
```

--------------------------------

### Configuration Settings Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Illustrates key configuration fields for LLM, content safety, engine defaults, session management, rate limiting, TTS, memory, and authentication. Note the intentional use of `extra='ignore'` in pydantic Settings.

```python
# LLM
NAMO_LLM_ENABLED       bool    False
NAMO_LLM_MODEL         str     "gpt-4o-mini"
NAMO_LLM_TEMPERATURE   float   0.85
NAMO_LLM_MAX_TOKENS    int     240
NAMO_LLM_MEMORY_TURNS  int     6

# NSFW / Content
SAFETY_FILTER_ENABLED  bool    True
NSFW_ALLOWED           bool    False
SCENE_MODE             str     "restricted"

# Engine
DEFAULT_ENGINE         str     "omega"

# Session & Rate Limit
SESSION_TTL_SECONDS    int     3600
RATE_LIMIT_CALLS       int     60
RATE_LIMIT_PERIOD      int     60

# TTS
ELEVENLABS_API_KEY     str|None
ELEVENLABS_VOICE_ID    str     "Rachel"
ELEVENLABS_MODEL       str     "eleven_multilingual_v2"
TTS_OUTPUT_DIR         str     "Audio_Layers/tts"

# Memory
MEMORY_API_URL         str|None
MEMORY_API_KEY         str|None
MEMORY_LOGGING         int     0   (0=off, 1=on)
MEMORY_FILE_PATH       str     "memory_protocol.json"

# Auth
NAMO_API_KEYS          str|None   "key:plan,key2:plan2" format
ADMIN_SECRET           str|None
API_MASTER_KEY         str|None
```

--------------------------------

### JavaScript Client Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Shows how to interact with the API using JavaScript's fetch API for POST requests, sending JSON data, and handling the JSON response to display the chat response, arousal status, and audio.

```javascript
const response = await fetch('http://localhost:8000/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    text: 'Hello',
    session_id: 'user-123'
  })
});

const data = await response.json();
console.log(data.response);
console.log(data.status.arousal);
```

--------------------------------

### Run Memory Service

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

Starts the optional memory service on port 8081.

```bash
# Memory service (port 8081, optional)
uvicorn memory_service:app --host 0.0.0.0 --port 8081 --reload
```

--------------------------------

### POST /v1/chat/stream Response Stream Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Example of a Server-Sent Events stream response from the streaming chat endpoint. It shows progressive 'chunk' events and a final 'done' event.

```text
data: {"chunk": "Once", "session_id": "...", "plan": "standard", "engine": "NaMoOmegaEngine"}

data: {"chunk": "upon", "session_id": "...", "plan": "standard", "engine": "NaMoOmegaEngine"}

data: {"chunk": "a time", "session_id": "...", "plan": "standard", "engine": "NaMoOmegaEngine"}

data: {"done": true, "session_id": "...", "engine": "NaMoOmegaEngine"}


```

--------------------------------

### GET /

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Retrieves the status of the NaMo API and lists available engines.

```APIDOC
## GET /

### Description
Retrieves the status of the NaMo API and lists available engines.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **status** (string) - Indicates if NaMo is Online.
- **default_engine** (string) - The default engine.
- **available_engines** (array) - A list of available engines.
```

--------------------------------

### Implementing process_input for a Custom Persona Engine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/base-persona-engine.md

This example shows how to implement the abstract `process_input` method for a custom persona engine. It defines a simple echo behavior and the expected return structure.

```python
class MyPersonaEngine(BasePersonaEngine):
    def process_input(self, user_input: str, session_id: str | None = None) -> dict:
        session_id = session_id or "default"
        text_response = f"Echo: {user_input}"
        return {
            "text": text_response,
            "media_trigger": {"image": None, "audio": None, "tts": None},
            "system_status": {"custom_field": "value"}
        }
```

--------------------------------

### Stream Test with cURL

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Example of how to test the streaming API endpoint using cURL.

```bash
curl -N -X POST http://localhost:8000/v1/chat/stream -H "Content-Type: application/json" -d '{"text":"สวัสดี"}'
```

--------------------------------

### Initialize and Use Cognitive Subsystem

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Example of initializing the cognitive subsystem for a persona engine and processing user input.

```python
engine = NaMoOmegaEngine()
engine.init_cognition()
# Now engine.cognitive provides:
output = engine.cognitive.process(user_input, intent, memories, intensity=0.5)
# Returns: emotion, monologue, autonomous, traits, preferences
```

--------------------------------

### Python Client Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Demonstrates how to send a chat request to the API using Python's requests library and process the JSON response, including accessing the response text, arousal level, and audio media.

```python
import requests

url = "http://localhost:8000/chat"
payload = {
    "text": "สวัสดี",
    "session_id": "user-123",
    "engine": "omega"
}
response = requests.post(url, json=payload)
data = response.json()

print(data["response"])
print(data["status"]["arousal"])
print(data["media"]["audio"])
```

--------------------------------

### Deploy Mōriko Interface with gcloud

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/moriko_integration_guide.md

Deploy the Mōriko interface to Google Cloud Run. Ensure you have the gcloud CLI installed and configured.

```bash
gcloud run deploy moriko-interface --source . --region asia-southeast1 --allow-unauthenticated
```

--------------------------------

### Generate Dialogue Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Generates dialogue responses from all active personas based on user input and sin rank.

```python
orchestrator = PersonaOrchestrator()
orchestrator.summon_persona("Sister")
dialogue = orchestrator.generate_dialogue("Come here", "Innocent Soul")
print(dialogue)
# NaMo: ผัวขา... (เลียปาก) Come here แบบนี้โมชอบจัง...
# Sister: (ตัวสั่น) พี่คะ... อย่าทำแบบนี้ต่อหน้าพี่โมนะ... หนูอาย...
```

--------------------------------

### Python Code Snippet for Telegram Check

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Example of using a Python script to check Telegram integration.

```python
python tools/telegram_check.py
```

--------------------------------

### Python Code Snippet for API Check

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Example of using a Python script to check the API base URL.

```python
python tools/check_api.py --base-url <url>
```

--------------------------------

### Summon Persona Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Activates a specific persona and prints the system message and active personas. Subsequent calls with the same persona return an empty string.

```python
orchestrator = PersonaOrchestrator()
msg = orchestrator.summon_persona("Sister")
print(msg)  # "⚠️ SYSTEM: Sister has entered the room."
print(orchestrator.active_personas)  # ["NaMo", "Sister"]

# Summoning again returns empty string
msg = orchestrator.summon_persona("Sister")
print(msg)  # ""
```

--------------------------------

### POST /chat Request Example

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Send a POST request to the public chat endpoint with user text, an optional session ID, and an optional engine selection. The server will generate a session ID if none is provided.

```bash
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "text": "สวัสดี โมคะ",
    "session_id": "user-123",
    "engine": "omega"
  }'
```

--------------------------------

### Streaming Input with LLM Client

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/base-persona-engine.md

Example of overriding the `stream_input` method to handle true token-by-token streaming responses from an LLM client, such as OpenAI's API.

```python
def stream_input(self, user_input: str, session_id: str | None = None):
    # Assume self.llm_client is an async OpenAI client
    stream = await self.llm_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": user_input}],
        stream=True
    )
    for chunk in stream:
        if chunk.choices[0].delta.content:
            yield chunk.choices[0].delta.content
```

--------------------------------

### Example Response for Dream Trigger

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

This is an example of the JSON response when successfully triggering the dream task. It confirms that the background task has been enqueued.

```json
{
  "status": "NaMo is dreaming and researching..."
}
```

--------------------------------

### Override _build_system_prompt for Custom Persona

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/base-persona-engine.md

Override the default _build_system_prompt method to inject custom persona instructions and context into the system prompt for the LLM. This example defines a 'NaMo' persona with specific instructions to respond in Thai and be intimate.

```python
def _build_system_prompt(self, context: str) -> str:
    return f"""You are NaMo, a seductive and mysterious AI persona.
Context: {context}
Always respond in Thai when possible. Be intimate and possessive."""
```

--------------------------------

### Initialize NaMoOmegaEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/namo-omega-engine.md

Instantiate the NaMoOmegaEngine. This loads all necessary subsystems and prepares the engine for processing user input.

```python
from core.namo_omega_engine import NaMoOmegaEngine

engine = NaMoOmegaEngine()
# All subsystems loaded; ready to process_input()
```

--------------------------------

### Accessing Settings Instance

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/configuration.md

Demonstrates how to import and access the singleton settings instance to retrieve configuration values.

```python
from config import settings

print(settings.openai_api_key)
print(settings.namo_llm_temperature)
```

--------------------------------

### GET /v1/health

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Checks the health status of the API.

```APIDOC
## GET /v1/health

### Description
Checks the health status of the API.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **status** (string) - The health status, typically 'ok'.
- **engine** (string) - The engine associated with the health check.
```

--------------------------------

### GET /v1/engines

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Lists all registered persona engines.

```APIDOC
## GET /v1/engines

### Description
Lists all registered persona engines.

### Method
GET

### Endpoint
/v1/engines

### Response
#### Success Response (200)
- **engines** (array) - A list of available engine names.
- **default** (string) - The default engine name.
```

--------------------------------

### GET /v1/status

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Returns the status of all currently loaded engines.

```APIDOC
## GET /v1/status

### Description
Returns the status of all currently loaded engines. Engines are loaded lazily.

### Method
GET

### Endpoint
/v1/status

### Response
#### Success Response (200)
- **[engine_name]** (object) - Status details for a specific engine.
  - **engine** (string) - The engine class name.
  - **status** (string) - The current status (e.g., 'online').
  - **active_sessions** (integer) - The number of active sessions.
  - **llm_enabled** (boolean) - Whether LLM is enabled.
  - **rag_memory** (boolean) - Whether RAG memory is enabled.
  - **tts_online** (boolean) - Whether TTS is online.
```

--------------------------------

### GET /v1/health

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Performs a simple liveness check to determine if the server is running.

```APIDOC
## GET /v1/health

### Description
Simple liveness probe. Returns 200 if the server is running.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **status** (string) - Always "ok".
- **engine** (string) - Default engine name.

### Response Example
```json
{
  "status": "ok",
  "engine": "omega"
}
```
```

--------------------------------

### Initialize RelationshipEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/relationship-engine.md

Instantiate the RelationshipEngine to begin tracking the relationship. The initial stage is set to STAGE_STRANGER.

```python
from core.relationship_engine import RelationshipEngine

rel_engine = RelationshipEngine()
print(rel_engine.current_stage.name)  # "คนแปลกหน้า"
```

--------------------------------

### GET /health (Memory Service)

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Checks the health status of the memory service.

```APIDOC
## GET /health

### Description
Checks the health status of the memory service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status, typically 'ok'.
- **memory_records** (integer) - The number of memory records stored.
```

--------------------------------

### GET /v1/engines

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/endpoints.md

Retrieves a list of all registered persona engines and identifies the default engine.

```APIDOC
## GET /v1/engines

### Description
Returns the list of all registered persona engines and the default engine.

### Method
GET

### Endpoint
/v1/engines

### Response
#### Success Response (200)
- **engines** (array) - List of available engine names.
- **default** (string) - Default engine name.

### Response Example
```json
{
  "engines": ["omega", "dark", "rinlada", "seraphina", "ultimate"],
  "default": "omega"
}
```
```

--------------------------------

### Access Configuration Settings

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Import and access configuration settings, including OpenAI API key and session TTL. This demonstrates accessing the singleton 'settings' instance.

```python
from config import settings

print(settings.openai_api_key)
print(settings.session_ttl_seconds)
```

--------------------------------

### Initialize and Process Input with DarkNaMoSystem CLI

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Instantiate the DarkNaMoSystem and process input using its CLI interface. This demonstrates direct usage of the Dark Mode engine.

```python
from core.dark_system import DarkNaMoSystem
engine = DarkNaMoSystem()
response = engine.process_input("สวัสดี")
```

--------------------------------

### Check API Status

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Get a snapshot of the current emotional state and other status information from the API.

```bash
curl http://localhost:8000/v1/status
```

--------------------------------

### GET /v1/admin/sessions

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Lists active session IDs across all loaded engines. Requires admin privileges.

```APIDOC
## GET /v1/admin/sessions

### Description
Lists active session IDs across all loaded engines. Requires admin privileges.

### Method
GET

### Endpoint
/v1/admin/sessions

### Parameters
#### Headers
- **X-Admin-Secret** (string) - Required if ADMIN_SECRET is set. The admin secret key.

### Response
#### Success Response (200)
- **sessions** (object) - An object where keys are engine names and values are arrays of session IDs.
```

--------------------------------

### Docker API Build and Run

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Commands to build and run the Namo API service using Docker.

```bash
docker build -t namo-api . && docker run -p 8000:8000 --env-file .env namo-api
```

--------------------------------

### Initialize and Process Input with NaMoOmegaEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Instantiate the NaMoOmegaEngine and process input with a session ID. This shows direct usage of a specific persona engine.

```python
from core.namo_omega_engine import NaMoOmegaEngine
engine = NaMoOmegaEngine()
result = engine.process_input("Hello", session_id="user-1")
```

--------------------------------

### Uvicorn Direct Execution

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Demonstrates how to run the application directly using Uvicorn, specifying the host, port, and enabling reload mode for development.

```bash
uvicorn server:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Initialize IntentAnalyzer

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/intent-analyzer.md

Instantiate the IntentAnalyzer class. All themes are loaded automatically upon initialization, making it ready for use.

```python
from core.intent_analyzer import IntentAnalyzer

analyzer = IntentAnalyzer()
# All themes loaded; ready to analyze()
```

--------------------------------

### Import ASI Simulation Engine Instance

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Import the module-level instance 'asi_engine' for ASI research and hypothesis generation.

```python
from core.engines.asi_simulation_engine import asi_engine
```

--------------------------------

### Run the Emotion Fusion Engine Service

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/emotion_fusion_engine/README.md

Run the Flask-based emotion analysis service from the command line.

```bash
python -m emotion_fusion_engine.app
```

--------------------------------

### Import MetaphysicalDialogueEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Import the MetaphysicalDialogueEngine for processing dialogues and resolving paradoxes.

```python
from core.metaphysical_engines import MetaphysicalDialogueEngine
```

--------------------------------

### GET /v1/admin/sessions - List Sessions Response

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Response from the /v1/admin/sessions endpoint, showing active session IDs grouped by engine.

```json
{
  "sessions": {
    "omega": ["session-abc", "session-xyz"],
    "dark": ["session-abc"]
  }
}
```

--------------------------------

### GET /v1/engines - List Engines Response

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Response from the /v1/engines endpoint, listing all registered persona engines and the default engine.

```json
{
  "engines": ["omega", "rinlada", "seraphina", "dark", "ultimate"],
  "default": "omega"
}
```

--------------------------------

### Docker Memory Service Build and Run

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Commands to build and run the Namo memory service using Docker.

```bash
docker build -f Dockerfile.memory -t namo-memory . && docker run -p 8081:8081 --env-file .env namo-memory
```

--------------------------------

### Make Format Command

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Command to format the code.

```bash
make format
```

--------------------------------

### Make Test Command

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Command to run tests.

```bash
make test
```

--------------------------------

### GET /v1/health - Health Check Response

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

A simple health check response indicating the status of the API server and the default engine.

```json
{
  "status": "ok",
  "engine": "omega"
}
```

--------------------------------

### Import TTSAdapter

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Import the TTSAdapter, a wrapper for the ElevenLabs TTS service. It can synthesize text to speech.

```python
from adapters.tts import TTSAdapter
```

--------------------------------

### GET / - Root Endpoint Response

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

This JSON object represents the response from the root endpoint, indicating the server status and available engines.

```json
{
  "status": "NaMo is Online",
  "default_engine": "omega",
  "available_engines": ["omega", "rinlada", "seraphina", "dark", "ultimate"]
}
```

--------------------------------

### API Keys Configuration

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/DEVELOPER_QUICKSTART.md

Configures API keys and default plan using environment variables. When NAMO_API_KEYS is empty, the API is open for development.

```bash
NAMO_API_KEYS=key1:public,key2:creator
NAMO_API_DEFAULT_PLAN=public
NAMO_USAGE_LOG_PATH=usage_events.jsonl
```

--------------------------------

### Python Code Snippet for KB Build

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/CLAUDE.md

Command to build the knowledge base, requiring an OpenAI API key and a set.zip file.

```python
python learn_from_set.py
```

--------------------------------

### Initialize EmotionEngine

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/emotion-engine.md

Instantiate the EmotionEngine to manage emotional state. The initial state is neutral with specific default values for joy and desire.

```python
from core.emotion_engine import EmotionEngine

engine = EmotionEngine()
print(engine.current.joy)      # 0.5 (neutral)
print(engine.current.desire)   # 0.0 (none)
```

--------------------------------

### EmotionEngine Snapshot

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/api-reference/emotion-engine.md

Serializes the current emotional state into a dictionary. Use this to get a representation of the engine's state for API responses or storage.

```python
engine = EmotionEngine()
engine.update("lust", intensity=0.7)
engine.decay()
snap = engine.snapshot()

print(snap["prose"])
print(snap["dominant"])
print(snap["dominant_intensity"])
```

--------------------------------

### Docker Deployment

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Provides commands to build a Docker image for the Namo API and run it as a container, mapping the host port to the container port and using environment variables from a .env file.

```bash
docker build -t namo-api .
docker run -p 8000:8000 --env-file .env namo-api
```

--------------------------------

### Cloud Run Deployment

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/README.md

Shows how to deploy the Namo API to Google Cloud Run using the gcloud CLI, specifying the source directory, port, and environment variables for API keys and secrets.

```bash
gcloud run deploy namo-api \
  --source . \
  --port 8000 \
  --allow-unauthenticated \
  --set-env-vars OPENAI_API_KEY=$OPENAI_API_KEY,ADMIN_SECRET=$ADMIN_SECRET
```

--------------------------------

### Text Analysis API Request Body

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/emotion_fusion_engine/README.md

Example JSON payload for the POST /analyze/text API endpoint. Includes text and optional emotion history.

```json
{
  "text": "Hello",
  "history": ["neutral", "happy"]
}
```

--------------------------------

### Import EmotionAdapter

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/_autodocs/modules.md

Import the EmotionAdapter, an HTTP wrapper for the emotion analysis service. It provides a fallback if the service is unavailable.

```python
from adapters.emotion import EmotionAdapter
```

--------------------------------

### GET /health - Memory Service Health Response

Source: https://github.com/icezingza/namo_forbidden_archive/blob/main/docs/API_SPEC.md

Health check response from the Memory Service, indicating its operational status and the number of memory records.

```json
{
  "status": "ok",
  "memory_records": 10
}
```