Active Graph

The Active Graph API is organized into topical modules. You can find detailed documentation for specific components by navigating to their respective modules in the sidebar. The API reference covers the following core areas:

• Runtime: The runtime loop, frames, budget, and status.
• Graph: Graph primitives including objects, relations, patches, views, and events.
• Behaviors: Behavior decorators and base classes.
• Tools: The @tool decorator and tool primitives.
• Store: Event stores (in-memory, SQLite, Postgres), URL parsing, and migration.
• Packs: Pack format primitives.
• Errors: The ActiveGraphError hierarchy.
• Observability: Accepted-event sinks, the metrics protocol, and shipped backends.
• Diligence pack: The v0.9 reference pack.

The ROADMAP.md file serves as a historical scoping document for the v1.3 development cycle. It outlines planned features, quality improvements, and architectural shifts.

Key Versioning Context:

• Current Status: The v1.3–v1.7 line has largely shipped. For live status of what is currently implemented, refer to CHANGELOG.md and CONTRACT.md.
• Roadmap Markers:
  • MUST: Required for the scoped version path.
  • SHOULD: Intended if it does not block release-quality MUST items.
  • DEFERRED: Recognized but intentionally not a blocker for the current cycle.
• Future Ideas: Valid candidates for future development that are not currently blocking the roadmap are maintained in FUTURE_IDEAS.md.

The Diligence pack is a reference implementation for investment diligence workflows. It is designed to handle tasks such as analyzing claims, evaluating evidence, identifying contradictions, assessing risks, and generating memos.

Key features:

• LLM-backed behaviors: Three core behaviors are powered by Large Language Models.
• Reproducible fixtures: The pack includes built-in fixtures to allow for reproducible demonstrations without requiring immediate LLM integration.

For developers looking to build their own packs, this pack serves as a primary reference implementation. See the Authoring packs guide for detailed instructions.

A fork is a branch from a parent run at a specific event. It shares the parent's event log up to a specified cutoff point (the fork point) and then maintains its own independent log.

Key Characteristics

• Shared Lineage: The fork inherits all events from the parent up to the --at-event cutoff. This cutoff is inclusive.
• Cheap Execution: Using the shared-lineage model and the cache layer, the framework replays the shared prefix against the fork's in-memory graph without re-executing LLM or tool calls. This makes forking efficient.
• Independence: Forks can be configured differently, run with different packs, and inspected side-by-side without affecting the parent's state.
• Verifiability: The fork's lineage is verifiable via the event log.

It is important to distinguish between these two error types to identify when the failure occurred in the data lifecycle:

• CorruptedEventPayloadError: Occurs at decode time. It fires when the framework attempts to read bytes from the disk (via Runtime.load, iter_events, activegraph inspect, or activegraph migrate) and finds that the payload column is not valid JSON.
• NonSerializableEventError: Occurs at encode time. It fires when a Python value is being written to the store and cannot be converted into a JSON-compatible format.

A relation_behavior is a primitive that implements coordination logic directly on a graph edge rather than on the endpoints. It is triggered by events that touch one of the edge's endpoints.

To use it, decorate a function with @relation_behavior and specify the relation_type it should monitor and the on event types it should react to.

from activegraph import relation_behavior

@relation_behavior(name="unblock", relation_type="depends_on", on=["task.completed"])
def unblock(relation, event, graph, ctx):
    # 'relation' provides access to .source and .target
    if event.payload["task_id"] == relation.source:
        graph.patch_object(relation.target, {"status": "open"})

When using FalkorDBGraphStore, the graph schema is optimized for native traversal using Cypher:

• Relations: Stored as native edges with a single fixed relationship type :AGRelation. The specific relation kind is stored in the type edge property. This allows for efficient traversal using property filters: MATCH (s)-[r:AGRelation {type: $t}]->(t).
• Nodes: All endpoints carry the :AGNode label. Real objects carry an additional :AGObject label.
• Placeholders: A 'dangling' endpoint (a node referenced by a relation but not existing as a full object) is identified as :AGNode AND NOT :AGObject. There is no explicit :AGPlaceholder label; nodes are demoted to placeholders automatically when their associated object is removed.

In Active Graph v1.1, the behavior of forking a runtime is being unified to ensure consistent LLM cache usage between in-process forks and persistent forks.

• In-process forks: Using Runtime.fork(at_event=...) automatically pre-populates the LLM cache from the parent's recorded llm.responded events up to the fork point.
• Persistent forks: Previously, loading a fork via SQLiteEventStore.fork_run() followed by Runtime.load(..., run_id=<fork>) would only see the fork's own events, causing it to replay LLM behaviors against the live provider instead of using the cache.
• v1.1 Improvement: Runtime.load for a fork run will now look up the parent's forked_at_event_id and pre-populate the cache from the parent's events through that point, ensuring symmetry between in-process and persistent forks.