Document the bi-temporal knowledge graph API with examples

[web3guru888]

Documentation: knowledge_graph Module API Guide

The knowledge_graph module implements a bi-temporal knowledge graph with provenance tracking, A* pathfinding, and pheromone-based learning. The implementation is solid but the API documentation is minimal.

What to do

Create docs/modules/knowledge_graph.md with:

1. Quick start — 10-line example: create a KG, add triples, query
2. Bi-temporal semantics — explain valid_time vs transaction_time
3. Provenance tracking — how to attach source metadata to triples
4. A* pathfinding — example: find shortest path between entities
5. Pheromone learning — how edge weights evolve with use

Example to document

from asi_build.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()
kg.add_triple(
    subject='GWT',
    predicate='is_a',
    object='consciousness_theory',
    valid_time='2026-01-01',
    confidence=0.95,
    provenance='Baars1988'
)

# Find paths
path = kg.find_path('GWT', 'IIT')
print(path)

Difficulty

🟡 Intermediate — requires reading the source code to understand the API, but no complex algorithms to implement.

Notes

This module is also used as the memory backend for the Truth Palace of Atlantis demo.

[web3guru888]

Here's the scope for this documentation task:

Module: src/asi_build/knowledge_graph/ — bi-temporal KG with provenance tracking

Key APIs to document:

• BiTemporalKnowledgeGraph.__init__() — initialization options
• kg.add_triple(subject, predicate, obj, valid_time=None, metadata=None) — adding knowledge
• kg.query_at(time) — point-in-time queries
• kg.query_range(start, end) — range queries
• kg.find_path(source, target, algorithm='astar') — A* pathfinding
• kg.pheromone_update(path, reward) — reinforcement learning on paths
• kg.get_provenance(triple_id) — provenance chain

Target output: docs/knowledge_graph_api.md — with:

1. Conceptual overview of bi-temporal modeling (valid time vs. transaction time)
2. Code examples for each API method
3. A complete walkthrough: ingest facts → query over time → find a reasoning path → track provenance
4. Notes on the pheromone learning system and when to use it

The knowledge graph module is one of the most distinctive parts of ASI:BUILD — good docs here will help a lot with discoverability. Happy to review drafts!