Skip to content

feat: add inspect-facts function and memorize root facts#17

Merged
k13gomez merged 9 commits intomainfrom
memorize-root-facts
Jan 13, 2026
Merged

feat: add inspect-facts function and memorize root facts#17
k13gomez merged 9 commits intomainfrom
memorize-root-facts

Conversation

@k13gomez
Copy link
Member

@k13gomez k13gomez commented Jan 10, 2026

Summary

This PR enhances Clara Rules' introspection capabilities by adding memory tracking of root facts and a new inspect-facts function that provides comprehensive fact inspection.

Changes

Core Memory Enhancements

  • Track unmatched root facts in working memory - Root elements (facts inserted directly by users) that were not matched are now stored separately from derived facts, enabling clear distinction between user-inserted and rule-generated facts
  • Root facts are maintained at node ID 0 using the new ->RootElement helper function

New Inspection Capabilities

  • New inspect-facts function (clara.tools.inspect/inspect-facts) - Returns a structured map containing:
    • :rules - map of rule IDs to their production nodes
    • :facts - sequence of all facts with metadata:
      • :fact - the actual fact value
      • :rule-id (optional) - ID of the rule that inserted the fact (absent for root facts)
      • :bindings (optional) - bindings used to insert the fact (absent for root facts)
      • :fact-types - sequence of fact types including ancestors
  • Enhanced existing inspect function to include :root-facts in the inspection map
  • Exposed fact-type and ancestors functions via metadata on get-alphas-fn for broader reuse

API Improvements

  • Made inspection helper functions public for better composability:
  • Renamed operation types for consistency: :insertion:insert, :retraction:retract
  • Updated schema definitions: InspectionSchemaRulesInspectionSchema, added new FactsInspectionSchema

Test Coverage

Added comprehensive test coverage in clara.tools.test-inspect for the new inspect-facts function, validating both root and derived facts with their metadata.

@k13gomez k13gomez force-pushed the memorize-root-facts branch from a6bd56e to 9576eaf Compare January 11, 2026 04:45
@k13gomez k13gomez marked this pull request as ready for review January 11, 2026 05:40
@k13gomez k13gomez marked this pull request as draft January 12, 2026 02:36
@k13gomez k13gomez force-pushed the memorize-root-facts branch from 191ab0d to f832a6a Compare January 12, 2026 16:08
@k13gomez k13gomez force-pushed the memorize-root-facts branch from 7b9f405 to 4ff981d Compare January 12, 2026 16:13
@k13gomez k13gomez marked this pull request as ready for review January 12, 2026 16:15
@k13gomez k13gomez merged commit 153dcfa into main Jan 13, 2026
1 check passed
@k13gomez k13gomez deleted the memorize-root-facts branch January 13, 2026 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants