EvoSpikeNet-BrainOS Detailed Specification

Copyright © 2026 Moonlight Technologies Inc. All Rights Reserved.

Version: v0.2.0
Last Updated: 2026-05-30

---

1. API Specification

1.1 REST API Endpoints Overview

All endpoints (except /health) require the X-API-Key header.

X-API-Key: <one from BRAINOS_API_KEYS>

1.2 Cognitive Functions

POST /api/v1/cognitive/decide

Executes PFC decision making.

Request:

{
  "objective": "navigate_to_goal",
  "options": ["path_a", "path_b", "path_c"],
  "context": {
    "scene": "outdoor",
    "weather": "clear",
    "time_of_day": "morning"
  },
  "constraints": ["avoid_stairs", "energy_efficient"]
}

Response:

{
  "decision_id": "uuid-v4",
  "recommended_action": "path_a",
  "confidence": 0.92,
  "reasoning": "Most efficient route with good visibility",
  "alternatives": [
    {
      "action": "path_b",
      "confidence": 0.05
    }
  ],
  "latency_ms": 42
}

Error Response:

{
  "detail": "Invalid objective format",
  "trace_id": "uuid-v4"
}

1.3 Safety Functions

POST /api/v1/safety/evaluate

Evaluates action safety.

Request:

{
  "action": "move_arm",
  "context": {
    "speed": "high",
    "nearby_objects": ["human", "fragile_item"],
    "environment": "warehouse"
  }
}

Response:

{
  "evaluation_id": "uuid-v4",
  "safety_level": "MEDIUM",
  "approved": false,
  "reason": "Human presence detected. Requires approval.",
  "human_approval_required": true,
  "approval_deadline_utc": "2026-05-30T14:35:00Z"
}

GET /api/v1/safety/pending

Lists pending human approvals.

Response:

{
  "pending_count": 3,
  "items": [
    {
      "approval_id": "uuid-v4",
      "action": "move_arm",
      "context": {"speed": "high"},
      "created_at_utc": "2026-05-30T14:30:00Z",
      "expires_at_utc": "2026-05-30T14:35:00Z"
    }
  ]
}

POST /api/v1/safety/approve/{id}

Approves a pending action.

Response:

{
  "approval_id": "uuid-v4",
  "status": "approved",
  "approved_at_utc": "2026-05-30T14:32:15Z"
}

POST /api/v1/safety/deny/{id}

Denies a pending action.

Response:

{
  "approval_id": "uuid-v4",
  "status": "denied",
  "denied_at_utc": "2026-05-30T14:32:15Z"
}

1.4 Memory Functions

POST /api/v1/memory/write

Records experience to memory.

Request:

{
  "context": {
    "location": "lab",
    "time": "2026-05-30T14:30:00Z",
    "scene_id": "lab-scene-001"
  },
  "action": "pick_object",
  "outcome": "success",
  "reward": 1.0,
  "metadata": {
    "object_type": "cube",
    "object_id": "obj-123",
    "grasp_type": "pinch"
  }
}

Response:

{
  "episode_id": "uuid-v4",
  "stored_at_utc": "2026-05-30T14:30:00Z",
  "memory_tier": "episodic"
}

POST /api/v1/memory/retrieve

Retrieves from memory.

Request:

{
  "query": "pick_object at lab",
  "limit": 10,
  "time_range": {
    "start": "2026-05-20T00:00:00Z",
    "end": "2026-05-30T23:59:59Z"
  },
  "filters": {
    "object_type": "cube"
  }
}

Response:

{
  "results_count": 3,
  "results": [
    {
      "episode_id": "uuid-v4",
      "timestamp": "2026-05-30T14:30:00Z",
      "context": {"location": "lab"},
      "action": "pick_object",
      "reward": 1.0,
      "relevance_score": 0.98
    }
  ]
}

GET /api/v1/memory/stats

Retrieves memory statistics.

Response:

{
  "working_memory": {
    "size_bytes": 1024000,
    "max_bytes": 5242880,
    "usage_percent": 19.5
  },
  "episodic_memory": {
    "total_episodes": 1523,
    "size_bytes": 104857600,
    "max_bytes": 1073741824,
    "usage_percent": 9.8,
    "hit_rate": 0.87
  },
  "long_term_memory": {
    "total_skills": 47,
    "size_bytes": 536870912,
    "max_bytes": 10737418240,
    "usage_percent": 5.0
  }
}

1.5 World Model

POST /api/v1/world/entities

Creates an entity.

Request:

{
  "entity_type": "robot",
  "rank": 5,
  "attributes": {
    "name": "robot-unit-1",
    "battery_percent": 85,
    "location": "lab"
  }
}

Response:

{
  "entity_id": "uuid-v4",
  "created_at_utc": "2026-05-30T14:30:00Z",
  "entity_type": "robot",
  "rank": 5
}

GET /api/v1/world/entities

Lists entities.

Response:

{
  "entities": [
    {
      "entity_id": "uuid-v4",
      "entity_type": "robot",
      "rank": 5,
      "attributes": {"name": "robot-unit-1"},
      "last_updated_utc": "2026-05-30T14:30:00Z"
    }
  ],
  "total_count": 15
}

GET /api/v1/world/entities/{id}

Gets a specific entity.

Response:

{
  "entity_id": "uuid-v4",
  "entity_type": "robot",
  "rank": 5,
  "attributes": {
    "name": "robot-unit-1",
    "battery_percent": 85,
    "location": "lab"
  },
  "created_at_utc": "2026-05-30T14:20:00Z",
  "last_updated_utc": "2026-05-30T14:30:00Z"
}

POST /api/v1/world/observe

Submits observation event.

Request:

{
  "event_type": "object_detected",
  "timestamp_utc": "2026-05-30T14:30:00Z",
  "source_entity_id": "uuid-v4",
  "target_entity_id": "uuid-v4",
  "data": {
    "confidence": 0.95,
    "bounding_box": [100, 200, 150, 250]
  }
}

Response:

{
  "observation_id": "uuid-v4",
  "processed_at_utc": "2026-05-30T14:30:00.123Z"
}

GET /api/v1/world/snapshot

Gets current world state snapshot.

Response:

{
  "snapshot_id": "uuid-v4",
  "timestamp_utc": "2026-05-30T14:30:00Z",
  "total_entities": 15,
  "entities_by_type": {
    "robot": 3,
    "object": 8,
    "sensor": 4
  },
  "active_decisions": 2,
  "pending_approvals": 1
}

1.6 Degradation Management

GET /api/v1/degradation/state

Gets current degradation state.

Response:

{
  "current_level": "ONLINE",
  "available_levels": ["ONLINE", "DEGRADED_ONLINE", "OFFLINE"],
  "failed_components": [],
  "recommended_actions": []
}

1.7 Audit & Verification

GET /api/v1/audit/verify

Verifies audit log hash chain.

Response:

{
  "verification_id": "uuid-v4",
  "status": "verified",
  "total_entries": 4521,
  "verified_entries": 4521,
  "verification_duration_ms": 156,
  "last_verified_utc": "2026-05-30T14:30:00Z"
}

GET /api/v1/audit/stats

Retrieves audit log statistics.

Response:

{
  "total_entries": 4521,
  "entries_by_type": {
    "decision": 1250,
    "safety_evaluation": 1100,
    "memory_operation": 800,
    "entity_modification": 600,
    "authentication": 771
  },
  "earliest_entry_utc": "2026-05-01T00:00:00Z",
  "latest_entry_utc": "2026-05-30T14:30:00Z",
  "size_bytes": 2097152
}

---

2. Python SDK Specification

2.1 Initialization

from brainos.client.sdk import BrainOSClient

with BrainOSClient(
    base_url="http://localhost:8000",
    api_key="your-api-key",
    timeout_seconds=30
) as client:
    # Client operations
    pass

2.2 Basic Methods

health() / is_alive()

Performs health check.

# Health check
health = client.health()  # → True/False

# Check if server is alive
if client.is_alive():
    print("Server is running")

decide(objective, options, context, constraints)

Calls PFC decision engine.

result = client.decide(
    objective="navigate_to_goal",
    options=["path_a", "path_b"],
    context={"scene": "outdoor"},
    constraints=["avoid_stairs"]
)

print(f"Decision: {result.recommended_action}")
print(f"Confidence: {result.confidence}")
print(f"Latency: {result.latency_ms}ms")

safety_evaluate(action, context)

Evaluates action safety.

evaluation = client.safety_evaluate(
    action="move_arm",
    context={"speed": "high", "nearby_objects": ["human"]}
)

if evaluation.approved:
    print("Action is safe to execute")
else:
    print(f"Action requires approval: {evaluation.reason}")
    if evaluation.human_approval_required:
        print(f"Approval deadline: {evaluation.approval_deadline_utc}")

safety_pending() / safety_approve(id) / safety_deny(id)

Manages human approval queue.

# List pending approvals
pending = client.safety_pending()
for item in pending.items:
    print(f"{item.approval_id}: {item.action}")

# Approve
client.safety_approve(approval_id)

# Deny
client.safety_deny(approval_id)

memory_write(context, action, reward, metadata)

Records to memory.

client.memory_write(
    context={"location": "lab", "time": "2026-05-30T14:30:00Z"},
    action="pick_object",
    reward=1.0,
    metadata={"object_type": "cube"}
)

memory_retrieve(query, limit, time_range, filters)

Retrieves from memory.

results = client.memory_retrieve(
    query="pick_object at lab",
    limit=10,
    time_range=("2026-05-20", "2026-05-30"),
    filters={"object_type": "cube"}
)

for episode in results.results:
    print(f"Episode: {episode.action}, Reward: {episode.reward}")

memory_stats()

Gets memory statistics.

stats = client.memory_stats()
print(f"Working memory usage: {stats.working_memory.usage_percent}%")
print(f"Episodic hit rate: {stats.episodic_memory.hit_rate}")

create_entity(entity_type, rank, attributes)

Creates an entity.

entity = client.create_entity(
    entity_type="robot",
    rank=5,
    attributes={"name": "robot-unit-1", "battery_percent": 85}
)
print(f"Created entity: {entity.entity_id}")

list_entities() / get_entity(id)

Retrieves entities.

# List all entities
entities = client.list_entities()

# Get specific entity
entity = client.get_entity(entity_id)

observe(event_type, context, data)

Submits observation event.

client.observe(
    event_type="object_detected",
    context={"source_entity_id": "uuid-1", "target_entity_id": "uuid-2"},
    data={"confidence": 0.95}
)

world_snapshot()

Gets world state snapshot.

snapshot = client.world_snapshot()
print(f"Total entities: {snapshot.total_entities}")
print(f"Active decisions: {snapshot.active_decisions}")

degradation_state()

Gets degradation state.

state = client.degradation_state()
print(f"Current level: {state.current_level}")

audit_verify() / audit_stats()

Audits and retrieves statistics.

# Verify
verification = client.audit_verify()
print(f"Verification status: {verification.status}")

# Statistics
stats = client.audit_stats()
print(f"Total entries: {stats.total_entries}")

---

3. Data Models

3.1 DecisionResult

class DecisionResult:
    decision_id: str  # UUID
    recommended_action: str
    confidence: float  # 0.0–1.0
    reasoning: str
    alternatives: list[Alternative]
    latency_ms: float

3.2 SafetyEvaluation

class SafetyEvaluation:
    evaluation_id: str  # UUID
    safety_level: str  # "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
    approved: bool
    reason: str
    human_approval_required: bool
    approval_deadline_utc: Optional[datetime]

3.3 Episode

class Episode:
    episode_id: str  # UUID
    timestamp: datetime
    context: dict
    action: str
    outcome: str  # "success" | "failure" | "partial"
    reward: float
    metadata: dict
    relevance_score: float  # 0.0–1.0

3.4 Entity

class Entity:
    entity_id: str  # UUID
    entity_type: str
    rank: int
    attributes: dict
    created_at_utc: datetime
    last_updated_utc: datetime

---

4. Environment Variables

4.1 Required Variables

Variable	Description	Example
BRAINOS_SERIALIZATION_KEY	HMAC-SHA256 shared secret (32+ bytes)	32-char random string
BRAINOS_API_KEYS	API key list (comma-separated)	key1,key2,key3

4.2 Optional Variables

Variable	Default	Description
BRAINOS_ENV	development	Runtime environment (development/staging/production)
BRAINOS_ALLOW_NO_AUTH	false	Allow unauthenticated access (must be false in production)
BRAINOS_ZENOH_ROUTER	tcp/zenoh-router:7447	Zenoh router address
BRAINOS_CORS_ORIGINS	*	CORS allowed origins (comma-separated)
LOG_LEVEL	INFO	Log level (DEBUG/INFO/WARNING/ERROR)

---

5. Error Handling

5.1 HTTP Status Codes

Code	Description
200	Success
400	Bad Request (input format error)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Not Found (resource not found)
500	Internal Server Error

5.2 Error Response Format

{
  "detail": "Error message",
  "trace_id": "uuid-v4",
  "timestamp_utc": "2026-05-30T14:30:00Z"
}

5.3 Python SDK Error Handling

from brainos.client.sdk import BrainOSError, AuthenticationError

try:
    result = client.decide(objective="test", options=[], context={})
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except BrainOSError as e:
    print(f"API error: {e}")

---

6. Test Scenarios

6.1 Phase 1: Foundation

52 tests passed

• Event bus communication
• API authentication & RBAC
• HMAC signature verification
• World Model entity operations
• Audit log hash chain

6.2 Phase 2: Cognitive Loop

78 tests passed

• PFC decision engine round-trip
• Conscience Circuit safety guard
• Graceful degradation
• Memory read/write
• Domain adapter integration

6.3 Phase 3 (R5): Cross-Platform-Client

27 tests passed

• Python SDK (Windows/Linux/macOS)
• PWA Web Dashboard
• Service Worker offline cache
• CORS middleware

---

7. Performance Metrics

7.1 Latency

Operation	Target	Measurement
Decision request (p95)	< 500 ms	Prometheus histogram
Memory write	< 100 ms	Transaction time
Memory retrieval	< 200 ms	Query execution time
Safety evaluation (p95)	< 300 ms	Evaluation processing time

7.2 Throughput

Operation	Target
Concurrent decision requests	100 req/s
Memory writes	1000 writes/s
Event bus pub/sub	10000 events/s

---

8. Production Security Checklist

Verify the following before deploying to production:

• [ ] Set BRAINOS_SERIALIZATION_KEY to random value of 32+ bytes
• [ ] Use same BRAINOS_SERIALIZATION_KEY on all nodes
• [ ] Enforce BRAINOS_ALLOW_NO_AUTH=false in production
• [ ] Set BRAINOS_ENV=production
• [ ] Restrict BRAINOS_CORS_ORIGINS to known origins only
• [ ] Manage BRAINOS_API_KEYS via secret management tool (Vault, etc.)
• [ ] Schedule audit log verification weekly minimum
• [ ] Store and monitor API access logs

---

Related Documents: - Overview Specification - Implementation Plan