EvoSpikeNet-BrainOS 詳細仕様書

Copyright © 2026 Moonlight Technologies Inc. All Rights Reserved.

バージョン: v0.2.0
最終更新日: 2026年5月30日

---

1. API 仕様

1.1 REST API エンドポイント一覧

すべてのエンドポイント（/health を除く）は X-API-Key ヘッダーを必須とします。

X-API-Key: <BRAINOS_API_KEYS から選択>

1.2 認知機能（Cognitive）

POST /api/v1/cognitive/decide

PFC による意思決定を実行します。

リクエスト:

{
  "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"]
}

レスポンス:

{
  "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
}

エラーレスポンス:

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

1.3 安全機能（Safety）

POST /api/v1/safety/evaluate

行動の安全性を評価します。

リクエスト:

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

レスポンス:

{
  "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

人間承認待ちのリストを取得します。

レスポンス:

{
  "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}

承認待ちのアクションを承認します。

レスポンス:

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

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

承認待ちのアクションを拒否します。

レスポンス:

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

1.4 メモリ機能（Memory）

POST /api/v1/memory/write

経験をメモリに記録します。

リクエスト:

{
  "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"
  }
}

レスポンス:

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

POST /api/v1/memory/retrieve

メモリから検索します。

リクエスト:

{
  "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"
  }
}

レスポンス:

{
  "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

メモリ統計情報を取得します。

レスポンス:

{
  "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

エンティティを作成します。

リクエスト:

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

レスポンス:

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

GET /api/v1/world/entities

エンティティリストを取得します。

レスポンス:

{
  "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}

特定のエンティティを取得します。

レスポンス:

{
  "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

観測イベントを入力します。

リクエスト:

{
  "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]
  }
}

レスポンス:

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

GET /api/v1/world/snapshot

現在の世界状態スナップショットを取得します。

レスポンス:

{
  "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）

GET /api/v1/degradation/state

現在の縮退状態を取得します。

レスポンス:

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

1.7 監査・検証（Audit）

GET /api/v1/audit/verify

監査ログのハッシュチェーンを検証します。

レスポンス:

{
  "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

監査ログの統計情報を取得します。

レスポンス:

{
  "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 仕様

2.1 初期化

from brainos.client.sdk import BrainOSClient

with BrainOSClient(
    base_url="http://localhost:8000",
    api_key="your-api-key",
    timeout_seconds=30
) as client:
    # クライアント操作
    pass

2.2 基本メソッド

health() / is_alive()

ヘルスチェックを実行します。

# ヘルスチェック
health = client.health()  # → True/False

# サーバーが生きているか確認
if client.is_alive():
    print("Server is running")

decide(objective, options, context, constraints)

PFC 決定エンジンを呼び出します。

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)

安全性を評価します。

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)

人間承認キューを管理します。

# 承認待ち一覧
pending = client.safety_pending()
for item in pending.items:
    print(f"{item.approval_id}: {item.action}")

# 承認
client.safety_approve(approval_id)

# 拒否
client.safety_deny(approval_id)

memory_write(context, action, reward, metadata)

メモリに記録します。

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)

メモリから検索します。

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()

メモリ統計を取得します。

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)

エンティティを作成します。

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)

エンティティを取得します。

# 全エンティティリスト
entities = client.list_entities()

# 特定のエンティティ
entity = client.get_entity(entity_id)

observe(event_type, context, data)

観測イベントを入力します。

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

world_snapshot()

世界状態スナップショットを取得します。

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

degradation_state()

縮退状態を取得します。

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

audit_verify() / audit_stats()

監査ログを検証・統計取得します。

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

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

---

3. データモデル

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. 環境変数

4.1 必須変数

変数	説明	例
BRAINOS_SERIALIZATION_KEY	HMAC-SHA256 共有秘密（32 バイト以上）	32 文字のランダム文字列
BRAINOS_API_KEYS	API キーリスト（カンマ区切り）	key1,key2,key3

4.2 オプション変数

変数	デフォルト	説明
BRAINOS_ENV	development	実行環境（development/staging/production）
BRAINOS_ALLOW_NO_AUTH	false	認証なしアクセス許可（本番環境では false 必須）
BRAINOS_ZENOH_ROUTER	tcp/zenoh-router:7447	Zenoh ルーターアドレス
BRAINOS_CORS_ORIGINS	*	CORS 許可オリジン（カンマ区切り）
LOG_LEVEL	INFO	ログレベル（DEBUG/INFO/WARNING/ERROR）

---

5. エラーハンドリング

5.1 HTTP ステータスコード

コード	説明
200	成功
400	Bad Request（入力形式エラー）
401	Unauthorized（API キー無効）
403	Forbidden（権限不足）
404	Not Found（リソース未検出）
500	Internal Server Error（サーバーエラー）

5.2 エラーレスポンス形式

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

5.3 Python SDK エラーハンドリング

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. テストシナリオ

6.1 フェーズ 1: Foundation

52 テストパス

• イベントバス疎通確認
• API 認証・RBAC
• HMAC 署名検証
• World Model エンティティ操作
• 監査ログハッシュチェーン

6.2 フェーズ 2: Cognitive Loop

78 テストパス

• PFC 決定エンジン往復
• Conscience Circuit 安全ガード
• 縮退動作
• メモリ読み書き
• ドメインアダプタ統合

6.3 フェーズ 3（R5）: Cross-Platform-Client

27 テストパス

• Python SDK (Windows/Linux/macOS)
• PWA Web Dashboard
• Service Worker オフラインキャッシュ
• CORS ミドルウェア

---

7. パフォーマンス指標

7.1 レイテンシ

操作	ターゲット	測定方法
決定リクエスト (p95)	< 500 ms	Prometheus ヒストグラム
メモリ書き込み	< 100 ms	トランザクション時間
メモリ検索	< 200 ms	クエリ実行時間
安全性評価 (p95)	< 300 ms	評価処理時間

7.2 スループット

操作	ターゲット
同時決定リクエスト	100 req/s
メモリ書き込み	1000 writes/s
イベントバス pub/sub	10000 events/s

---

8. セキュリティ製品チェックリスト

本番環境へのデプロイ前に以下を確認してください：

• [ ] BRAINOS_SERIALIZATION_KEY を 32 バイト以上のランダム値に設定
• [ ] すべてのノードで同じ BRAINOS_SERIALIZATION_KEY を使用
• [ ] BRAINOS_ALLOW_NO_AUTH=false を本番環境で強制
• [ ] BRAINOS_ENV=production を設定
• [ ] BRAINOS_CORS_ORIGINS を既知のオリジンのみに制限
• [ ] BRAINOS_API_KEYS をシークレット管理ツール（Vault など）で管理
• [ ] 監査ログ検証を週1回以上スケジュール
• [ ] API アクセスログを保存・監視

---

関連ドキュメント: - 概要仕様書 - 実装プラン