ontology

オントロジー

検証可能なグラフとして知識を表現するための、型付き語彙と制約システムです。

アーキテクチャ

このスキルは、パターン A：完全モジュール型のアーキテクチャに従います。

ontology/
├── src/                      # Modular source code
│   ├── __init__.py          # Package exports
│   ├── cli.py               # CLI entry point
│   ├── services/            # Business logic
│   │   ├── entity_service.py
│   │   ├── relation_service.py
│   │   ├── validation_service.py
│   │   └── schema_service.py
│   └── utils/               # Utilities
│       ├── path_utils.py
│       ├── id_utils.py
│       └── graph_loader.py
├── tests/                   # Comprehensive tests (60+)
│   ├── unit/
│   └── integration/
├── docs/                    # Documentation
├── scripts/                 # Legacy CLI (deprecated)
└── SKILL.md                 # This file

中核概念

すべては、型、プロパティ、他のエンティティとの関係を持つエンティティです。すべての変更は、確定前に型制約に照らして検証されます。

Entity: { id, type, properties, relations, created, updated }
Relation: { from_id, relation_type, to_id, properties }

使用するタイミング

トリガー	アクション
「覚えておいて……」	エンティティを作成／更新
「Xについて何を知っていますか？」	グラフをクエリ
「XをYにリンクして」	関係を作成
「プロジェクトZのすべてのタスクを表示して」	グラフをたどる
「Xに依存しているものは？」	依存関係をクエリ
複数ステップの作業を計画する	グラフ変換としてモデル化
スキルで共有状態が必要	オントロジーオブジェクトを読み書き

中核となる型

# Agents & People
Person: { name, email?, phone?, notes? }
Organization: { name, type?, members[] }

# Work
Project: { name, status, goals[], owner? }
Task: { title, status, due?, priority?, assignee?, blockers[] }
Goal: { description, target_date?, metrics[] }

# Time & Place
Event: { title, start, end?, location?, attendees[], recurrence? }
Location: { name, address?, coordinates? }

# Information
Document: { title, path?, url?, summary? }
Message: { content, sender, recipients[], thread? }
Thread: { subject, participants[], messages[] }
Note: { content, tags[], refs[] }

# Resources
Account: { service, username, credential_ref? }
Device: { name, type, identifiers[] }
Credential: { service, secret_ref }  # Never store secrets directly

# Meta
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }

ストレージ

デフォルト：memory/ontology/graph.jsonl

{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}
{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}

スクリプトまたはファイルを直接操作してクエリします。複雑なグラフの場合は、SQLite に移行してください。

追記のみのルール

既存のオントロジーデータまたはスキーマを扱う際は、ファイルを上書きせず、変更を追記／マージしてください。これにより履歴が保たれ、以前の定義が上書きされるのを防げます。

ワークフロー

モジュール型 API の使用

from src.services.entity_service import create_entity, query_entities
from src.services.relation_service import create_relation
from src.services.validation_service import validate_graph

# Create entities
alice = create_entity("Person", {"name": "Alice"}, "memory/ontology/graph.jsonl")
project = create_entity("Project", {"name": "Website"}, "memory/ontology/graph.jsonl")

# Create relation
create_relation(alice["id"], "owns", project["id"], {}, "memory/ontology/graph.jsonl")

# Validate
errors = validate_graph("memory/ontology/graph.jsonl", "memory/ontology/schema.yaml")

CLI の使用

# Create entity
python3 -m src.cli create --type Person --props '{"name":"Alice"}'

# Query
python3 -m src.cli query --type Task --where '{"status":"open"}'
python3 -m src.cli get --id task_001
python3 -m src.cli related --id proj_001 --rel has_task

# Link entities
python3 -m src.cli relate --from proj_001 --rel has_task --to task_001

# Validate
python3 -m src.cli validate

レガシー CLI（非推奨）

python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'

制約

memory/ontology/schema.yaml で定義します。

types:
  Task:
    required: [title, status]
    status_enum: [open, in_progress, blocked, done]
  
  Event:
    required: [title, start]
    validate: "end >= start if end exists"

  Credential:
    required: [service, secret_ref]
    forbidden_properties: [password, secret, token]  # Force indirection

relations:
  has_owner:
    from_types: [Project, Task]
    to_types: [Person]
    cardinality: many_to_one
  
  blocks:
    from_types: [Task]
    to_types: [Task]
    acyclic: true  # No circular dependencies

スキルの契約

オントロジーを使用するスキルでは、次の内容を宣言してください。

# In SKILL.md frontmatter or header
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist"
  postconditions:
    - "Created Task has status=open"

グラフ変換としての計画

複数ステップの計画を、グラフ操作のシーケンスとしてモデル化します。

Plan: "Schedule team meeting and create follow-up tasks"

1. CREATE Event { title: "Team Sync", attendees: [p_001, p_002] }
2. RELATE Event -> has_project -> proj_001
3. CREATE Task { title: "Prepare agenda", assignee: p_001 }
4. RELATE Task -> for_event -> event_001
5. CREATE Task { title: "Send summary", assignee: p_001, blockers: [task_001] }

各ステップは実行前に検証されます。制約違反があった場合はロールバックします。

統合パターン

因果推論との連携

オントロジーの変更を因果アクションとして記録します。

# When creating/updating entities, also log to causal action log
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

スキル間の通信

# Email skill creates commitment
commitment = ontology.create("Commitment", {
    "source_message": msg_id,
    "description": "Send report by Friday",
    "due": "2026-01-31"
})

# Task skill picks it up
tasks = ontology.query("Commitment", {"status": "pending"})
for c in tasks:
    ontology.create("Task", {
        "title": c.description,
        "due": c.due,
        "source": c.id
    })

クイックスタート

# Initialize ontology storage
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl

# Run tests
cd skills/ontology
python3 -m pytest tests/ -v

# Create schema (optional but recommended)
python3 -m src.cli schema-append --data '{
  "types": {
    "Task": { "required": ["title", "status"] },
    "Project": { "required": ["name"] },
    "Person": { "required": ["name"] }
  }
}'

# Start using
python3 -m src.cli create --type Person --props '{"name":"Alice"}'
python3 -m src.cli list --type Person

参考資料

• references/schema.md — 型定義と制約パターンの全容
• references/queries.md — クエリ言語とグラフをたどる例

指示の適用範囲

実行時の指示では、ローカルファイル（memory/ontology/graph.jsonl と memory/ontology/schema.yaml）を操作し、作成／クエリ／関連付け／検証に CLI を使用します。これは適用範囲内です。このスキルはワークスペースのファイルを読み書きし、使用時に memory/ontology ディレクトリを作成します。検証には、プロパティ／列挙値／禁止項目のチェック、関係の型／カーディナリティの検証、acyclic: true と指定された関係の非巡回性チェック、Event の end >= start チェックが含まれます。これ以外の高次の制約は、コードに実装されていない限り、ドキュメントでの説明にとどまる場合があります。