Initial commit with translated description
This commit is contained in:
211
references/queries.md
Normal file
211
references/queries.md
Normal file
@@ -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)
|
||||
```
|
||||
322
references/schema.md
Normal file
322
references/schema.md
Normal file
@@ -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"
|
||||
```
|
||||
Reference in New Issue
Block a user