User Stories

1
Feature: Cortex Initialization
2
  
3
  Scenario: Initialize Cortex with a model
4
    Given a configured environment
5
    When I call Cortex.init with model "smollm2-135m"
6
    Then the model weights should be downloaded (if not cached)
7
    And the model should be loaded into memory
8
    And the Cortex instance should be ready for inference
9
  
10
  Scenario: List available models
11
    Given an initialized SDK
12
    When I call Cortex.listModels()
13
    Then I should receive an array of available models with their sizes and capabilities

1
Feature: Text Completion
2
  
3
  Scenario: Generate a simple completion
4
    Given an initialized Cortex instance
5
    When I call cortex.complete() with prompt "Hello, my name is"
6
    Then I should receive a streaming response with generated tokens
7
    And the response should complete within the configured timeout
8
  
9
  Scenario: Generate with system prompt
10
    Given an initialized Cortex instance
11
    When I call cortex.complete() with a system prompt and user prompt
12
    Then the model should follow the system prompt instructions
13
    And respond appropriately to the user prompt
14
  
15
  Scenario: Generate structured JSON output
16
    Given an initialized Cortex instance
17
    When I call cortex.complete() with a JSON schema constraint
18
    Then the response should be valid JSON matching the schema

1
Feature: Inference Resilience
2
  
3
  Scenario: Model load failure
4
    Given a device with insufficient RAM
5
    When Cortex.init() fails
6
    Then the SDK should throw a specific "insufficient_resources" error
7
    And the game should be able to fall back to "Legacy Rules" mode
8
  
9
  Scenario: Inference timeout
10
    Given a complex prompt
11
    When the model takes longer than 2000ms to respond
12
    Then the SDK should abort the request
13
    And return a pre-defined "Default Fallback" response (e.g., "...")

1
Feature: Agent Creation
2
  
3
  Scenario: Create agent with persona
4
    Given an initialized Cortex instance
5
    When I call Agent.create() with a persona string and initial state
6
    Then an Agent instance should be created
7
    And the agent should have an empty memory store
8
    And the agent should be ready to process inputs
9
  
10
  Scenario: Create agent from Soul (import)
11
    Given a Soul exported to IPFS
12
    When I call Agent.fromSoul() with the IPFS CID
13
    Then the agent should be restored with its persona, memories, and state
14
    And the agent should behave consistently with its previous incarnation

1
Feature: Agent Processing
2
  
3
  Scenario: Process dialogue input
4
    Given an agent with persona "a suspicious merchant"
5
    And the agent has memory of being cheated by the player
6
    When I call agent.process() with input "Want to make a deal?"
7
    Then the response should include dialogue reflecting suspicion
8
    And the response may include an action object
9
  
10
  Scenario: Process with context
11
    Given an agent with persona "a guard"
12
    When I call agent.process() with input "Let me through"
13
    And context includes { playerHasPass: true }
14
    Then the response action should be { type: 'ALLOW_PASSAGE' }
15
  
16
  Scenario: Invalid action rejected by Bridge
17
    Given an agent with persona "a merchant"
18
    When the agent attempts to trade an item it doesn't possess
19
    Then the Bridge should reject the action
20
    And return an error with reason "ITEM_NOT_IN_INVENTORY"

1
Feature: Memory Storage
2
  
3
  Scenario: Store a text observation
4
    Given an agent with an empty memory store
5
    When I call agent.memory.store() with text "The player saved my life"
6
    Then the text should be embedded as a vector
7
    And stored in the agent's memory database
8
    And associated with a timestamp
9
  
10
  Scenario: Store a structured event
11
    Given an agent with an existing memory
12
    When I call agent.memory.store() with an event object
13
    Then the event should be serialized to text
14
    And embedded and stored with metadata

1
Feature: Memory Retrieval
2
  
3
  Scenario: Recall by semantic similarity
4
    Given an agent with memories about "the player's betrayal" and "a sunny day"
5
    When I call agent.memory.recall() with query "trust issues"
6
    Then the memory about betrayal should be returned
7
    And the sunny day memory should not be returned
8
  
9
  Scenario: Recall with limit
10
    Given an agent with 100 memories
11
    When I call agent.memory.recall() with limit 5
12
    Then at most 5 memories should be returned
13
    And they should be ordered by relevance score

1
Feature: Action Validation
2
  
3
  Scenario: Valid action passes validation
4
    Given a Bridge configured with game rules
5
    And an agent with inventory ["sword", "shield"]
6
    When the agent outputs action { type: 'EQUIP', item: 'sword' }
7
    Then the Bridge should validate the action as VALID
8
    And return the action for execution
9
  
10
  Scenario: Invalid action rejected
11
    Given a Bridge configured with game rules
12
    And an agent with inventory ["sword"]
13
    When the agent outputs action { type: 'EQUIP', item: 'shield' }
14
    Then the Bridge should reject the action as INVALID
15
    And return error { reason: 'ITEM_NOT_OWNED', item: 'shield' }
16
  
17
  Scenario: Custom validation rules
18
    Given a Bridge with custom rule "players cannot trade during combat"
19
    When an agent attempts a TRADE action during combat state
20
    Then the Bridge should reject with reason 'INVALID_DURING_COMBAT'

1
Feature: GM Override
2
  
3
  Scenario: Inject scripted dialogue
4
    Given an agent in the middle of a "Thinking" loop
5
    When I call agent.override({ dialogue: "Follow me, quickly!" })
6
    Then the agent should immediately output that dialogue
7
    And the AI context should ideally update to remember it said that
8
  
9
  Scenario: Force movement
10
    Given an agent deciding where to go
11
    When I call agent.override({ action: { type: 'MOVE', target: 'door' } })
12
    Then the agent should execute the move immediately
13
    And bypass the usual validation rules (GM Authority)

1
Feature: Soul Export
2
  
3
  Scenario: Export to local JSON
4
    Given an agent with persona, memories, and state
5
    When I call agent.exportSoul({ format: 'json' })
6
    Then I should receive a JSON object containing all agent data
7
    And the JSON should follow the Soul schema
8
  
9
  Scenario: Export to IPFS
10
    Given an agent with memories
11
    When I call agent.exportSoul({ storage: 'ipfs' })
12
    Then the Soul should be uploaded to IPFS
13
    And I should receive the IPFS CID
14
    And the Soul should be retrievable via the CID

1
Feature: Soul Import
2
  
3
  Scenario: Import from IPFS CID
4
    Given a Soul exported with CID "bafybeif..."
5
    When I call Agent.fromSoul({ cid: 'bafybeif...' })
6
    Then the agent should be restored with its original persona
7
    And all memories should be restored
8
    And the agent state should match the export
9
  
10
  Scenario: Import with state merge
11
    Given an existing agent and a Soul from another application
12
    When I call agent.mergeSoul() with the foreign Soul
13
    Then the agent's memories should include both sets
14
    And conflicting state should be resolved per merge rules

1
Feature: Ghost Agent Testing
2
  
3
  Scenario: Run exploration test
4
    Given a level with multiple paths
5
    When I run a Ghost Agent with goal "maximize exploration"
6
    Then the agent should traverse all accessible areas
7
    And report exploration coverage percentage
8
  
9
  Scenario: Detect dead-end
10
    Given a level with an impassable bug
11
    When I run a Ghost Agent
12
    And the agent gets stuck for > 60 seconds
13
    Then the run should flag a "potential dead-end" at the location
14
    And capture a screenshot
15
  
16
  Scenario: Batch testing with seeds
17
    Given 10 procedurally generated levels
18
    When I run Ghost Agents on all levels in parallel
19
    Then I should receive aggregate metrics (completion rate, avg time, failures)

1
Feature: Reasoning Inspection
2
  
3
  Scenario: View internal monologue
4
    Given an agent has just performed an action
5
    When I query the agent's debug logs
6
    Then I should see the "Thought" chain that led to the "Action"
7
    And I should see which Memories were recalled for context
8
  
9
  Scenario: Real-time debug stream
10
    Given a game running in "Debug Mode"
11
    When an agent "thinks"
12
    Then the SDK should emit a `debug:thought` event with the raw SLM reasoning

1
Feature: Usage Monitoring
2
  
3
  Scenario: Track session tokens
4
    Given an active game session
5
    When an agent generates dialogue
6
    Then the token usage count should increment
7
    And I should be able to set a hard limit to prevent overn-runs
8
  
9
  Scenario: View dashboard metrics
10
    Given a dashboard user
11
    When I view the "Usage" tab
12
    Then I should see a breakdown of Local (Free) vs. Cloud (Paid) inference calls