Skip to content

Add relationship indexing, graph traversal, and activity tracking#15

Merged
mgoldsborough merged 2 commits intomainfrom
feat/relationship-graph
Mar 27, 2026
Merged

Add relationship indexing, graph traversal, and activity tracking#15
mgoldsborough merged 2 commits intomainfrom
feat/relationship-graph

Conversation

@mgoldsborough
Copy link
Copy Markdown
Contributor

Summary

  • Relationship index — write-time reverse index at _index/relations.json enables O(1) relationship lookups. Auto-rebuilds from entity files if missing or corrupt. Atomic writes via temp file + os.replace.
  • Graph traversal — three new methods on UpjackApp: query_by_relationship, get_related (forward/reverse), get_composite (entity + all related in one call with _related key)
  • Activity tracking — opt-in via "activities": true in manifest. Activities are regular entities (prefix act) with log_activity and get_activities convenience methods using the reverse index.
  • CRUD hookson_relationships_changed callback on create/update/delete, auto-wired by UpjackApp to maintain the index
  • MCP tools — per-entity: query_{plural}_by_relationship, get_related_{name}, get_{name}_composite. Global: rebuild_index, log_activity, get_activities

Test plan

  • 374 tests pass (make check)
  • 20 relation index tests (CRUD, rebuild, query, corrupt recovery)
  • 21 graph traversal tests (prefix resolution, query_by_relationship, get_related, get_composite)
  • 22 activity tests (schema, manifest parsing, log/get, indexing, lifecycle)
  • 8 CRUD hook tests (create/update/delete callbacks, soft vs hard delete)
  • 6 index wiring tests (UpjackApp auto-maintains index)
  • 16 MCP tool tests (relationship + activity tools through server interface)
  • 8 integration tests against real CRM/Todo example schemas

Closes #12

Write-time reverse index at _index/relations.json enables efficient
relationship queries without full entity scans. Three new graph
traversal methods on UpjackApp: query_by_relationship, get_related,
and get_composite. Activity tracking is opt-in via manifest flag,
using regular entities with a subject relationship.

New MCP tools auto-registered per entity type:
query_{plural}_by_relationship, get_related_{name},
get_{name}_composite, plus global rebuild_index and activity tools.

Closes #12
- _matches_filter now raises ValueError on unsupported dict/operator
  filters instead of silently skipping them
- get_composite returns a shallow copy with _related instead of
  mutating the original entity dict
@mgoldsborough mgoldsborough added the qa-reviewed QA review completed with no critical issues label Mar 27, 2026
@mgoldsborough mgoldsborough merged commit 118f70f into main Mar 27, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

qa-reviewed QA review completed with no critical issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add relationship indexing, graph traversal, and activity tracking

1 participant