openclaw-node-harness 2.0.0

package/skills/ontology/references/queries.md

@@ -0,0 +1,211 @@
+# Query Reference
+
+Query patterns and graph traversal examples.
+
+## Basic Queries
+
+### Get by ID
+
+```bash
+python3 scripts/ontology.py get --id task_001
+```
+
+### List by Type
+
+```bash
+# All tasks
+python3 scripts/ontology.py list --type Task
+
+# All people
+python3 scripts/ontology.py list --type Person
+```
+
+### Filter by Properties
+
+```bash
+# Open tasks
+python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
+
+# High priority tasks
+python3 scripts/ontology.py query --type Task --where '{"priority":"high"}'
+
+# Tasks assigned to specific person (by property)
+python3 scripts/ontology.py query --type Task --where '{"assignee":"p_001"}'
+```
+
+## Relation Queries
+
+### Get Related Entities
+
+```bash
+# Tasks belonging to a project (outgoing)
+python3 scripts/ontology.py related --id proj_001 --rel has_task
+
+# What projects does this task belong to (incoming)
+python3 scripts/ontology.py related --id task_001 --rel part_of --dir incoming
+
+# All relations for an entity (both directions)
+python3 scripts/ontology.py related --id p_001 --dir both
+```
+
+### Common Patterns
+
+```bash
+# Who owns this project?
+python3 scripts/ontology.py related --id proj_001 --rel has_owner
+
+# What events is this person attending?
+python3 scripts/ontology.py related --id p_001 --rel attendee_of --dir outgoing
+
+# What's blocking this task?
+python3 scripts/ontology.py related --id task_001 --rel blocked_by --dir incoming
+```
+
+## Programmatic Queries
+
+### Python API
+
+```python
+from scripts.ontology import load_graph, query_entities, get_related
+
+# Load the graph
+entities, relations = load_graph("memory/ontology/graph.jsonl")
+
+# Query entities
+open_tasks = query_entities("Task", {"status": "open"}, "memory/ontology/graph.jsonl")
+
+# Get related
+project_tasks = get_related("proj_001", "has_task", "memory/ontology/graph.jsonl")
+```
+
+### Complex Queries
+
+```python
+# Find all tasks blocked by incomplete dependencies
+def find_blocked_tasks(graph_path):
+    entities, relations = load_graph(graph_path)
+    blocked = []
+    
+    for entity in entities.values():
+        if entity["type"] != "Task":
+            continue
+        if entity["properties"].get("status") == "blocked":
+            # Find what's blocking it
+            blockers = get_related(entity["id"], "blocked_by", graph_path, "incoming")
+            incomplete_blockers = [
+                b for b in blockers 
+                if b["entity"]["properties"].get("status") != "done"
+            ]
+            if incomplete_blockers:
+                blocked.append({
+                    "task": entity,
+                    "blockers": incomplete_blockers
+                })
+    
+    return blocked
+```
+
+### Path Queries
+
+```python
+# Find path between two entities
+def find_path(from_id, to_id, graph_path, max_depth=5):
+    entities, relations = load_graph(graph_path)
+    
+    visited = set()
+    queue = [(from_id, [])]
+    
+    while queue:
+        current, path = queue.pop(0)
+        
+        if current == to_id:
+            return path
+        
+        if current in visited or len(path) >= max_depth:
+            continue
+        
+        visited.add(current)
+        
+        for rel in relations:
+            if rel["from"] == current and rel["to"] not in visited:
+                queue.append((rel["to"], path + [rel]))
+            if rel["to"] == current and rel["from"] not in visited:
+                queue.append((rel["from"], path + [{**rel, "direction": "incoming"}]))
+    
+    return None  # No path found
+```
+
+## Query Patterns by Use Case
+
+### Task Management
+
+```bash
+# All my open tasks
+python3 scripts/ontology.py query --type Task --where '{"status":"open","assignee":"p_me"}'
+
+# Overdue tasks (requires custom script for date comparison)
+# See references/schema.md for date handling
+
+# Tasks with no blockers
+python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
+# Then filter in code for those with no incoming "blocks" relations
+```
+
+### Project Overview
+
+```bash
+# All tasks in project
+python3 scripts/ontology.py related --id proj_001 --rel has_task
+
+# Project team members
+python3 scripts/ontology.py related --id proj_001 --rel has_member
+
+# Project goals
+python3 scripts/ontology.py related --id proj_001 --rel has_goal
+```
+
+### People & Contacts
+
+```bash
+# All people
+python3 scripts/ontology.py list --type Person
+
+# People in an organization
+python3 scripts/ontology.py related --id org_001 --rel has_member
+
+# What's assigned to this person
+python3 scripts/ontology.py related --id p_001 --rel assigned_to --dir incoming
+```
+
+### Events & Calendar
+
+```bash
+# All events
+python3 scripts/ontology.py list --type Event
+
+# Events at a location
+python3 scripts/ontology.py related --id loc_001 --rel located_at --dir incoming
+
+# Event attendees
+python3 scripts/ontology.py related --id event_001 --rel attendee_of --dir incoming
+```
+
+## Aggregations
+
+For complex aggregations, use Python:
+
+```python
+from collections import Counter
+
+def task_status_summary(project_id, graph_path):
+    """Count tasks by status for a project."""
+    tasks = get_related(project_id, "has_task", graph_path)
+    statuses = Counter(t["entity"]["properties"].get("status", "unknown") for t in tasks)
+    return dict(statuses)
+
+def workload_by_person(graph_path):
+    """Count open tasks per person."""
+    open_tasks = query_entities("Task", {"status": "open"}, graph_path)
+    workload = Counter(t["properties"].get("assignee") for t in open_tasks)
+    return dict(workload)
+```

package/skills/ontology/references/schema.md

@@ -0,0 +1,322 @@
+# Ontology Schema Reference
+
+Full type definitions and constraint patterns for the ontology graph.
+
+## Core Types
+
+### Agents & People
+
+```yaml
+Person:
+  required: [name]
+  properties:
+    name: string
+    email: string?
+    phone: string?
+    organization: ref(Organization)?
+    notes: string?
+    tags: string[]?
+
+Organization:
+  required: [name]
+  properties:
+    name: string
+    type: enum(company, team, community, government, other)?
+    website: url?
+    members: ref(Person)[]?
+```
+
+### Work Management
+
+```yaml
+Project:
+  required: [name]
+  properties:
+    name: string
+    description: string?
+    status: enum(planning, active, paused, completed, archived)
+    owner: ref(Person)?
+    team: ref(Person)[]?
+    goals: ref(Goal)[]?
+    start_date: date?
+    end_date: date?
+    tags: string[]?
+
+Task:
+  required: [title, status]
+  properties:
+    title: string
+    description: string?
+    status: enum(open, in_progress, blocked, done, cancelled)
+    priority: enum(low, medium, high, urgent)?
+    assignee: ref(Person)?
+    project: ref(Project)?
+    due: datetime?
+    estimate_hours: number?
+    blockers: ref(Task)[]?
+    tags: string[]?
+
+Goal:
+  required: [description]
+  properties:
+    description: string
+    target_date: date?
+    status: enum(active, achieved, abandoned)?
+    metrics: object[]?
+    key_results: string[]?
+```
+
+### Time & Location
+
+```yaml
+Event:
+  required: [title, start]
+  properties:
+    title: string
+    description: string?
+    start: datetime
+    end: datetime?
+    location: ref(Location)?
+    attendees: ref(Person)[]?
+    recurrence: object?  # iCal RRULE format
+    status: enum(confirmed, tentative, cancelled)?
+    reminders: object[]?
+
+Location:
+  required: [name]
+  properties:
+    name: string
+    address: string?
+    city: string?
+    country: string?
+    coordinates: object?  # {lat, lng}
+    timezone: string?
+```
+
+### Information
+
+```yaml
+Document:
+  required: [title]
+  properties:
+    title: string
+    path: string?  # Local file path
+    url: url?      # Remote URL
+    mime_type: string?
+    summary: string?
+    content_hash: string?
+    tags: string[]?
+
+Message:
+  required: [content, sender]
+  properties:
+    content: string
+    sender: ref(Person)
+    recipients: ref(Person)[]
+    thread: ref(Thread)?
+    timestamp: datetime
+    platform: string?  # email, slack, whatsapp, etc.
+    external_id: string?
+
+Thread:
+  required: [subject]
+  properties:
+    subject: string
+    participants: ref(Person)[]
+    messages: ref(Message)[]
+    status: enum(active, archived)?
+    last_activity: datetime?
+
+Note:
+  required: [content]
+  properties:
+    content: string
+    title: string?
+    tags: string[]?
+    refs: ref(Entity)[]?  # Links to any entity
+    created: datetime
+```
+
+### Resources
+
+```yaml
+Account:
+  required: [service, username]
+  properties:
+    service: string  # github, gmail, aws, etc.
+    username: string
+    url: url?
+    credential_ref: ref(Credential)?
+
+Device:
+  required: [name, type]
+  properties:
+    name: string
+    type: enum(computer, phone, tablet, server, iot, other)
+    os: string?
+    identifiers: object?  # {mac, serial, etc.}
+    owner: ref(Person)?
+
+Credential:
+  required: [service, secret_ref]
+  forbidden_properties: [password, secret, token, key, api_key]
+  properties:
+    service: string
+    secret_ref: string  # Reference to secret store (e.g., "keychain:github-token")
+    expires: datetime?
+    scope: string[]?
+```
+
+### Meta
+
+```yaml
+Action:
+  required: [type, target, timestamp]
+  properties:
+    type: string  # create, update, delete, send, etc.
+    target: ref(Entity)
+    timestamp: datetime
+    actor: ref(Person|Agent)?
+    outcome: enum(success, failure, pending)?
+    details: object?
+
+Policy:
+  required: [scope, rule]
+  properties:
+    scope: string  # What this policy applies to
+    rule: string   # The constraint in natural language or code
+    enforcement: enum(block, warn, log)
+    enabled: boolean
+```
+
+## Relation Types
+
+### Ownership & Assignment
+
+```yaml
+owns:
+  from_types: [Person, Organization]
+  to_types: [Account, Device, Document, Project]
+  cardinality: one_to_many
+
+has_owner:
+  from_types: [Project, Task, Document]
+  to_types: [Person]
+  cardinality: many_to_one
+
+assigned_to:
+  from_types: [Task]
+  to_types: [Person]
+  cardinality: many_to_one
+```
+
+### Hierarchy & Containment
+
+```yaml
+has_task:
+  from_types: [Project]
+  to_types: [Task]
+  cardinality: one_to_many
+
+has_goal:
+  from_types: [Project]
+  to_types: [Goal]
+  cardinality: one_to_many
+
+member_of:
+  from_types: [Person]
+  to_types: [Organization]
+  cardinality: many_to_many
+
+part_of:
+  from_types: [Task, Document, Event]
+  to_types: [Project]
+  cardinality: many_to_one
+```
+
+### Dependencies
+
+```yaml
+blocks:
+  from_types: [Task]
+  to_types: [Task]
+  acyclic: true  # Prevents circular dependencies
+  cardinality: many_to_many
+
+depends_on:
+  from_types: [Task, Project]
+  to_types: [Task, Project, Event]
+  acyclic: true
+  cardinality: many_to_many
+
+requires:
+  from_types: [Action]
+  to_types: [Credential, Policy]
+  cardinality: many_to_many
+```
+
+### References
+
+```yaml
+mentions:
+  from_types: [Document, Message, Note]
+  to_types: [Person, Project, Task, Event]
+  cardinality: many_to_many
+
+references:
+  from_types: [Document, Note]
+  to_types: [Document, Note]
+  cardinality: many_to_many
+
+follows_up:
+  from_types: [Task, Event]
+  to_types: [Event, Message]
+  cardinality: many_to_one
+```
+
+### Events
+
+```yaml
+attendee_of:
+  from_types: [Person]
+  to_types: [Event]
+  cardinality: many_to_many
+  properties:
+    status: enum(accepted, declined, tentative, pending)
+
+located_at:
+  from_types: [Event, Person, Device]
+  to_types: [Location]
+  cardinality: many_to_one
+```
+
+## Global Constraints
+
+```yaml
+constraints:
+  # Credentials must never store secrets directly
+  - type: Credential
+    rule: "forbidden_properties: [password, secret, token]"
+    message: "Credentials must use secret_ref to reference external secret storage"
+
+  # Tasks must have valid status transitions
+  - type: Task
+    rule: "status transitions: open -> in_progress -> (done|blocked) -> done"
+    enforcement: warn
+
+  # Events must have end >= start
+  - type: Event
+    rule: "if end exists: end >= start"
+    message: "Event end time must be after start time"
+
+  # No orphan tasks (should belong to a project or have explicit owner)
+  - type: Task
+    rule: "has_relation(part_of, Project) OR has_property(owner)"
+    enforcement: warn
+    message: "Task should belong to a project or have an explicit owner"
+
+  # Circular dependency prevention
+  - relation: blocks
+    rule: "acyclic"
+    message: "Circular task dependencies are not allowed"
+```