BRING v2 is a production‑ready, AI‑powered platform for building, exploring, and living in persistent fantasy worlds.
It combines generative world construction, graph‑based knowledge management, deterministic probability systems, intelligent narrative orchestration, and immersive roleplay – all driven by large language models (LLMs) and FAISS‑accelerated memory.

“From a single prompt to a living, breathing world – where every NPC remembers, every action has a chance, and the story never stops.”

User (CLI / Web UI)
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│                      world_cli.py (unified)                 │
│   Routes to builder, explorer, intelligence, narrative,     │
│   and new commands: newgame, continue, serve                │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      RoleplayEngine                          │
│  (narrator / NPC / scene agents, probability system,        │
│   romance engine, memory, start resolver)                   │
└──────────────┬──────────────────────────────┬───────────────┘
               │                              │
               ▼                              ▼
┌──────────────────────────┐    ┌────────────────────────────┐
│      StoryEngine         │    │        Director            │
│  (event generation,      │    │ (villains, story planner,  │
│   effect application,    │    │  NPC simulator, tick loop) │
│   probability actions)   │    └──────────────┬─────────────┘
└──────────────┬───────────┘                   │
               │                               │
               ▼                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 Unified EntityStore + GraphStore            │
│   O(1) name index, batch saves, mutation callbacks.        │
│   Lazy graph rebuild, branch manager.                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     WorldMemory (FAISS)                     │
│   Partitioned storage, embedding queue, write‑behind,      │
│   cognitive pipeline (entity extraction, contradiction,    │
│   pain signals), background optimizer.                     │
└─────────────────────────────────────────────────────────────┘

All modules share world_db/ – everything is persistent, atomic, and crash‑safe.

git clone https://github.com/Eva.E1/BRING.git
cd BRING

# Install dependencies
pip install -r requirements.txt

# For FAISS (highly recommended)
pip install faiss-cpu   # or faiss-gpu if you have CUDA

Create a .env file (or copy the template):

cp .env.example .env

Edit .env:

# LLM (OpenAI or compatible)
WORLD_LLM_BASE_URL=https://api.openai.com/v1
WORLD_LLM_API_KEY=your_openai_api_key
WORLD_LLM_MODEL=gpt-4o-mini

# Optional: Local embeddings (e.g., BGE‑M3 via LiteLLM or local server)
WORLD_EMBEDDING_BASE_URL=http://localhost:8043/v1
WORLD_EMBEDDING_MODEL=bge-m3

# Database location
WORLD_DB_PATH=./world_db

# Classic: build world, layers, relationships
python -m world_builder.cli build --episodes 3 --relationships

# Or start a new game immediately (birth wizard + web UI)
python world_cli.py newgame --hints "a young elven ranger" --isekai

The newgame command:

• Checks system (LLM, FAISS, disk space)
• Prepares world (creates frame if missing)
• Runs the advanced birth wizard (probability rolls for race, class, magic, talents)
• Generates a full family tree, heirloom, and family secret
• Schedules childhood milestones (first word, first step, magic awakening)
• Launches the web UI at http://localhost:8000

# CLI summary
python -m world_builder.cli view summary

# List all characters
python -m world_builder.cli view characters

# Detailed entity view
python -m world_builder.cli view entity "Kaelen" --level 2

# Semantic search
python -m world_explorer.cli search "ancient prophecy" --semantic

python -m world_narrative.cli play --character Kaelen --location Silverwood

Inside the session:

• Natural language: I search the old chest for clues.
• Talk to NPCs: talk to Elara "What do you know about the ruins?"
• Move: go to Riverfall
• Probability actions: /attack Goblin, /persuade Elara "We should help", /stealth
• Romance: /romance Kaelen Elara (shows status), /romance-attempt confess --character Kaelen --target Elara
• Slash commands: /look, /inventory, /status, /quests, /time, /save, /quit

The Director runs in the background – villains advance, chance events occur, story beats trigger.

python world_cli.py serve --port 8000

Then open http://localhost:8000.
The UI provides a terminal‑style interface with:

• Real‑time memory event feed
• Character and romance dashboards
• Quest tracking
• Probability sparkline
• Full command palette (Ctrl+K)

Purpose: Create and expand the world skeleton.

Key improvement (v2): Batch saves and lazy graph rebuild drastically reduce I/O.

Purpose: Navigate the graph, visualise, manage branches, and now includes the full web UI.

New in v2: The web UI is now the primary interface for newgame. It includes real‑time WebSocket feeds for memory and roleplay.

Purpose: Analyse, recommend, and enrich the world automatically.

v2 performance: All duplicate detection and relationship repair now use FAISS and tries, making them O(log n) instead of O(n²).

Purpose: Run the living story – director, roleplay, probability, romance, memory, quests.

Director background loop: Wakes every 60 real seconds, advances story time by 30 minutes, processes NPC interactions, villain ticks, chance events, and scheduled story beats.

Now integrated into RoleplayEngine and StoryEngine. Used for:

• Combat – /attack
• Persuasion – /persuade
• Stealth – /stealth
• Intimidation – /intimidate
• Deception – /deception
• Romance – all romance actions
• Birth – race, social class, magic affinity, talents
• Quest objectives – chance‑based objectives

Profiles: combat, persuasion, stealth, romance, investigation, athletics, deception, intimidation, generic, birth_race, birth_social_class, birth_magic_affinity, birth_talent.

Modifiers: temporary bonuses/penalties via /prob modify.

Automatically tracks relationships between characters. CLI commands:

• romance-status --character Kaelen --target Elara
• romance-attempt confess --character Kaelen --target Elara --location "Moonlight Garden"
• romance-list --status dating
• romance-gift --character Kaelen --target Elara --gift "Silver Necklace"

Integration: Romance events are logged to the chronicler and can trigger director story arcs.

Used internally by newgame and continue. Features:

• System check – verifies LLM, FAISS, disk space.
• World preparation – creates world frame if missing.
• Memory health check – runs consolidation before start.
• Birth wizard – probability rolls + LLM generation.
• Post‑birth tasks – repairs relationships, schedules childhood milestones, adds welcome quest.
• Snapshot save/load – instantly resume games.

New components:

• UnifiedEntityStore – O(1) name resolution, batch saves, mutation callbacks.
• EventBus – decoupled publish/subscribe for all modules.
• WorldMemory – FAISS‑based, partitioned, self‑optimising.
• ProbabilityEngine – deterministic rolls with modifiers.
• RomanceEngine – relationship management.

Start a new game with web UI:

python world_cli.py newgame --hints "a young elven ranger named Kaelen" --isekai

The browser opens with a terminal‑style interface.
You see the opening narrative (birth scene), family tree, and a status panel.

Natural Language Actions:

> I look around the forest clearing.

[Narrator] Sunlight filters through the ancient oaks, dappling the mossy ground. A small stream babbles nearby. You notice a worn path leading east, and a strange symbol carved into a stone.

Movement:

> go to Riverfall
> head north through the archway
> climb the old tower stairs

Talking to NPCs:

> talk to Elara "Do you know about the symbol on that stone?"

Elara says: "Ah, that's the mark of the Wardens. They used to guard this forest, but they vanished a century ago. Some say a curse drove them out."

Multi-turn Conversations:

> ask Elara about the Wardens
> follow up with "Where did they go?"
> persuade Elara "We should investigate together"

All skill-based actions use the deterministic probability system:

> /attack Goblin

[Narrator] Kaelen attacks Goblin: success (prob 72%, roll 0.34). The goblin takes 10 damage!

Available Action Types:

Check current relationship status:

> /romance-status --character Kaelen --target Elara

💖 Kaelen & Elara
Status: crush
Affection: 55%
Compatibility: 68%
Stage: attraction

Romance Progression Stages:

1. Neutral → No romantic interest yet
2. Attraction → Mutual interest detected
3. Crush → One-sided strong feelings
4. Dating → Officially in a relationship
5. Engaged → Promise to marry
6. Married → Lifelong commitment

Romance Actions:

# Attempt to confess feelings
> /romance-attempt confess --character Kaelen --target Elara --location "Moonlight Garden"

✅ Confess result: Kaelen confesses his feelings to Elara amazingly. She accepts!

# Go on a date
> /romance-attempt date --character Kaelen --target Elara --activity "walk by the lake"

# Give a gift (boosts affection)
> /romance-gift --character Kaelen --target Elara --gift "Silver Necklace"

# Propose marriage (requires high affection & dating status)
> /romance-attempt propose --character Kaelen --target Elara --ring "Family Heirloom Ring"

Factors Affecting Romance Success:

• Affection Level: Higher = better success rate
• Compatibility: Based on personality traits, values, background
• Current Mood: NPCs have dynamic emotional states
• Location: Romantic settings provide bonuses
• Gifts: Thoughtful gifts boost affection
• Previous Interactions: History matters

Character Status:

> /status
> /inventory
> /quests
> /skills
> /relationships

World Interaction:

> /look          # Describe current location
> /time          # Show current in-game time
> /map           # Display known areas
> /who           # List NPCs in current location

Session Management:

> /save my_adventure    # Save current progress
> /load my_adventure    # Resume saved game
> /export character     # Export character data as JSON
> /quit                 # End session (auto-saves)

1. Use Third Person: Describe your actions as "Kaelen draws his sword" not "I draw my sword"
2. Be Specific: "I carefully examine the lock for tumblers" works better than "I check the door"
3. Engage with NPCs: Ask follow-up questions, remember their stories
4. Think About Consequences: Actions affect reputation, relationships, and story direction
5. Use the Environment: Interact with objects, use terrain advantages
6. Let the Story Unfold: Sometimes failure creates better narratives than success

Combat Encounter:

> /attack the goblin raiders
> take cover behind the stone wall
> /intimidate the remaining goblins "Surrender or die!"
> loot the goblin chief's body

Social Intrigue:

> attend the noble's banquet
> talk to Lord Blackwood "Your reputation precedes you"
> /persuade Blackwood "We share common interests here"
> /deceive the guard "I'm a visiting merchant from the south"
> sneak into the private chambers
> /investigate the locked desk

Romantic Subplot:

> invite Elara to dinner at the inn
> /romance-gift --target Elara --gift "bouquet of moonflowers"
> talk to Elara "I've been thinking about what you said..."
> /romance-attempt confess --target Elara

Mystery Investigation:

> /investigate the crime scene
> examine the broken window
> talk to the witness "What did you see that night?"
> /investigate the muddy footprints
> connect the clues in my journal
> confront the suspect with the evidence

Create alternate timelines without affecting the main story:

# Create a new branch
world branch create what-if-kaelen-dies

# Switch to the branch
world branch switch what-if-kaelen-dies

# Make changes (delete edges, add nodes, play differently)
# ...

# Merge back to main timeline when ready
world branch merge what-if-kaelen-dies

Use Cases:

• Test different story outcomes
• Explore "what if" scenarios
• Run parallel campaigns with same world
• Experiment with character decisions

Begin your game at any point with natural language:

world narrative play --start "as Kaelen in the Silverwood forest at dawn, just after a storm"

The system will:

1. Locate relevant entities (Kaelen, Silverwood forest)
2. Set appropriate time and weather conditions
3. Generate an opening scene matching the context
4. Position NPCs based on their schedules and relationships

Examples:

# Start mid-action
world narrative play --start "during a tavern brawl, Kaelen is outnumbered"

# Start at a specific event
world narrative play --start "at the royal ball, moments before the assassination attempt"

# Start with a mystery
world narrative play --start "waking up in a locked room with no memory of how you got here"

Temporarily boost or penalize skill checks:

# Give Kaelen a temporary +20% combat boost for 5 minutes (300 seconds)
world narrative prob modify Kaelen combat_skill 0.2 --duration 300

# Add a situational penalty (-15% to stealth due to heavy armor)
world narrative prob modify Kaelen stealth -0.15 --reason "wearing plate armor"

# List all active modifiers
world narrative prob list --character Kaelen

# Remove a specific modifier
world narrative prob modify Kaelen combat_skill --remove

# Clear all modifiers for a character
world narrative prob modify Kaelen --clear-all

Common Modifier Scenarios:

• Buffs: Magic spells, potions, morale bonuses, terrain advantages
• Debuffs: Injuries, fatigue, curses, environmental hazards
• Situational: Night vision bonuses, ranged penalties in melee, language barriers

Manage the AI's long-term memory system:

# Full maintenance (prune old memories, merge similar events, archive)
world narrative memory-maintenance --full

# Check memory status and statistics
world narrative memory-status

# Forget low-importance memories from last 30 days
world narrative memory-forget 30 --min-importance 0.2

# Summarize memories tagged with specific keywords
world narrative memory-summarise --tag "isekai"
world narrative memory-summarise --tag "villain plot"

# Export memories for backup or analysis
world narrative memory-export --output memories_backup.json

# Import memories from another session
world narrative memory-import --file memories_from_other_game.json

Memory System Features:

• Automatic Consolidation: Similar events merge into cohesive narratives
• Importance Scoring: Critical events preserved, trivial details pruned
• Time-Based Partitioning: Recent memories more accessible than old ones
• Semantic Search: Find memories by meaning, not just keywords

Automatically improve world consistency and depth:

# Full enrichment pipeline (recommended)
world intel enrich --fix-rules

# Individual enrichment steps
world intel check-rules --fix          # Validate entity consistency
world intel recommend                  # Suggest new relationships
world intel deduplicate                # Merge duplicate entities
world intel expand "Location:Silverwood" --depth 2  # Flesh out subgraph

What Enrichment Does:

• Completes missing L1/L2/L3 layers for entities
• Detects and fixes contradictory information
• Identifies isolated nodes and suggests connections
• Merges near-duplicate characters/locations
• Generates missing backstory elements
• Validates all entities against world rules

Export and explore your world as an interactive graph:

# Generate interactive HTML visualization
world explore visualize --output myworld.html

# Open in browser (Linux/Mac)
xdg-open myworld.html    # Linux
open myworld.html        # Mac
start myworld.html       # Windows

Visualization Features:

• Zoomable, pannable network graph
• Color-coded entity types (characters, locations, items, factions)
• Click nodes to see full details
• Highlight relationships and connection paths
• Filter by entity type or relationship type
• Search and highlight specific entities

Start the backend server for custom integrations:

world serve --port 8000

Available API Endpoints:

Example API Usage:

# Start a new game via API
curl -X POST http://localhost:8000/api/launch \
  -H "Content-Type: application/json" \
  -d '{"hints": "dwarven cleric", "isekai": false}'

# Query romance status
curl http://localhost:8000/api/romance/status?character=Kaelen\&target=Elara

# Perform probability check
curl -X POST http://localhost:8000/api/probability/roll \
  -H "Content-Type: application/json" \
  -d '{"character": "Kaelen", "action": "persuade", "target": "Guard"}'

Customize the background story director behavior:

# View current director status
world narrative director-status

# Adjust tick rate (default: 60 real seconds = 30 game minutes)
# Edit .env: WORLD_DIRECT_TICK_INTERVAL=120

# Force immediate story advancement
world narrative tick now

# Schedule a custom event
world narrative schedule villain_event 30 '{"villain":"The Shadow","location":"Dark Tower"}'

Director Responsibilities:

• Advances story time automatically
• Processes NPC daily routines and interactions
• Triggers villain plot progression
• Generates random encounters and events
• Manages quest updates and completions
• Evolves the world (new NPCs, locations, items)

Tools for troubleshooting and development:

# View detailed entity information
world explore show "Character:Kaelen" --complete

# Trace relationship paths
world explore path "Kaelen" "Ancient Prophecy" --depth 3

# Check graph health
world builder validate

# Repair broken relationships
world builder repair --intelligent --merge --create

# View system performance stats
world narrative memory-status --verbose

# Export session logs for debugging
world narrative export-session --format json --output debug_log.json

All settings via environment variables (.env).

BRING/
├── world_builder/          # World generation
│   ├── builder.py          # Main orchestrator (batch saves, event bus)
│   ├── cli.py              # Typer CLI
│   ├── generator.py        # LLM prompt calls
│   ├── graph_manager.py    # Unified API over EntityStore
│   └── ...
├── world_explorer/         # Graph navigation & web UI
│   ├── cli.py
│   ├── store.py            # GraphStore with unified store
│   ├── navigator.py        # Queries (neighbors, path, search)
│   ├── branch_manager.py
│   ├── api.py              # FastAPI (serves UI + REST + WebSocket)
│   ├── templates.py        # Inline HTML/JS UI
│   └── routes/             # Modular API routes
├── world_intelligence/     # Analysis & enrichment (FAISS accelerated)
│   ├── cli.py
│   ├── graph_analyzer.py
│   ├── recommender.py
│   ├── rule_checker.py
│   ├── duplicate_detector.py (FAISS)
│   ├── relationship_repairer.py (Trie + fuzzy)
│   └── pipeline.py
├── world_narrative/        # Story & roleplay
│   ├── cli.py (includes newgame, continue, romance, prob)
│   ├── context.py          # Dependency injection (memory, probability, romance)
│   ├── story_engine.py
│   ├── director.py         # Unified background director
│   ├── memory_optimized.py # NPC memory
│   ├── birth.py            # Advanced character creation (family tree, isekai)
│   ├── launcher.py         # Professional game launcher
│   └── ...
├── world_engine/           # Roleplay agents (probability actions)
├── world_director/         # Task queue, arcs, evolution
├── world_core/             # Shared infrastructure
│   ├── models.py           # LayeredProfile, EntityNode, WorldFrame
│   ├── store.py            # UnifiedEntityStore (O(1) lookups)
│   ├── event_bus.py        # Async pub/sub
│   ├── history_manager.py  # Persistent session turns
│   ├── probability/        # Probability engine & profiles
│   ├── romance/            # Romance engine & models
│   └── memory/             # FAISS‑based self‑optimising memory
│       ├── world_memory.py
│       ├── optimizer.py
│       ├── partition.py
│       └── ...
└── world_db/               # Persistent data (auto‑created)

We welcome contributions! Please:

1. Open an issue describing the change.
2. Fork the repo and create a feature branch.
3. Add tests for new features.
4. Run black and isort (if configured).
5. Submit a pull request.

Development setup:

git clone https://github.com/Eva.E1/BRING.git
cd BRING
pip install -r requirements.txt
pip install faiss-cpu
cp .env.example .env

Testing the new game pipeline:

python world_cli.py newgame --hints "test" --no-browser
python test_integration.py

Apache 2.0

Enjoy building and living in your worlds with BRING v2!
May your stories be legendary.