Active Graph

https://github.com/yoheinakajima/activegraph
Admin
An event-sourced reactive graph runtime for long-running, auditable, agentic systems with behaviors...
Tokens:128,737
Snippets:1,833
Trust Score:8
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run ActiveGraph quickstart demo or interactive tutorial

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

Initiates the ActiveGraph quickstart process. By default, it runs a bundled demo using fixtures without requiring an API key or network access. Use the --interactive flag to start a guided REPL for writing and testing behaviors.

```bash
activegraph quickstart [--interactive]
```

--------------------------------

### Quick Start Active Graph

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs the Active Graph package and runs the quick start command to get started.

```bash
pip install activegraph
activegraph quickstart
```

--------------------------------

### Start Interactive Quickstart with ActiveGraph

Source: https://github.com/yoheinakajima/activegraph/blob/main/examples/quickstart_session.txt

Initiate the interactive quickstart process using the `activegraph quickstart --interactive` command. This command guides users through creating and implementing their first custom behavior with prompts and explanations.

```bash
$ activegraph quickstart --interactive
```

--------------------------------

### Postgres Setup for Production

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/operating-in-production.md

Install the necessary package for Postgres support and ensure you have a compatible database version. Schema creation is handled automatically on the first connection.

```bash
createdb activegraph_prod
pip install 'activegraph[postgres]'
```

--------------------------------

### Quick Fix for Missing Dependency

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/missing-optional-dependency.md

This example shows the typical error message and the recommended pip command to install the missing optional dependency for a specific subsystem.

```text
MissingOptionalDependency: PostgresEventStore requires the
'psycopg' Python package

How to fix:
  Install the optional dependency:
      pip install 'activegraph[postgres]'
```

--------------------------------

### ActiveGraph Quickstart Modes

Source: https://github.com/yoheinakajima/activegraph/blob/main/CONTRACT.md

The v1.0 quickstart command supports two modes: a fixture-backed diligence demo and an interactive tutorial walk-through. Both modes conclude by directing users to relevant documentation.

```bash
activegraph quickstart                # fixture-backed diligence demo
activegraph quickstart --interactive  # tutorial walk-through
```

--------------------------------

### Install All Active Graph Features

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs all available features for Active Graph.

```bash
pip install "activegraph[all]"
```

--------------------------------

### Initialize Runtime with Prometheus Metrics

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/operating-in-production.md

Example of initializing the ActiveGraph Runtime with PrometheusMetrics. Ensure 'prometheus_client' is installed via 'pip install "activegraph[prometheus]"'.

```python
from activegraph.observability import PrometheusMetrics
rt = Runtime(graph, metrics=PrometheusMetrics())
```

--------------------------------

### Install Activegraph

Source: https://github.com/yoheinakajima/activegraph/blob/main/examples/quickstart_session.txt

Install the Activegraph package using pip. This is the only installation step required for the demo path.

```bash
$ pip install activegraph
> Collecting activegraph
>   ...
> Successfully installed activegraph-1.0.0 click-8.x pydantic-2.x
```

--------------------------------

### Verify Package Installation and Functionality

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/about/publishing.md

Steps to create a virtual environment, install the published package, and verify its version and basic functionality. This is a crucial post-publish check.

```bash
python -m venv /tmp/verify-publish
source /tmp/verify-publish/bin/activate
pip install activegraph==1.0.0rc2
activegraph --version    # should print 1.0.0rc2
activegraph quickstart   # should run end-to-end against fixtures
deactivate
rm -rf /tmp/verify-publish
```

--------------------------------

### Initialize Runtime with OpenTelemetry Metrics

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/operating-in-production.md

Example of initializing the ActiveGraph Runtime with OpenTelemetryMetrics. Ensure 'opentelemetry-api' and 'opentelemetry-sdk' are installed via 'pip install "activegraph[opentelemetry]"'.

```python
from activegraph.observability import OpenTelemetryMetrics
rt = Runtime(graph, metrics=OpenTelemetryMetrics())
```

--------------------------------

### Run Bundled Demo

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/quickstart.md

Execute the bundled quickstart demo of ActiveGraph. This demo runs with recorded fixtures and is byte-deterministic.

```bash
activegraph quickstart
```

--------------------------------

### Runtime Initialization in v0.7

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/cookbook/migration-from-v0-7.md

Example of initializing the Runtime in v0.7 using a file path for persistence.

```python
# v0.7:
rt = Runtime(graph, persist_to="/path/to/run.db")
```

--------------------------------

### Example: Real-time Diligence Script

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Runnable end-to-end demo script for performing diligence operations in real-time. This example showcases practical application of the framework.

```python
examples/diligence_real_run.py
```

--------------------------------

### Install Prometheus for ActiveGraph

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/cookbook/migration-from-v0-7.md

Install the Prometheus backend for the metrics protocol by installing the `prometheus` extra for the ActiveGraph package.

```bash
pip install 'activegraph[prometheus]'
```

--------------------------------

### Install Active Graph with Prometheus Metrics

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with Prometheus metrics support.

```bash
pip install "activegraph[prometheus]"
```

--------------------------------

### Install ActiveGraph

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/quickstart.md

Install the ActiveGraph package using pip and verify the installation by checking the version.

```bash
pip install activegraph
activegraph --version
```

--------------------------------

### Install Active Graph with OpenTelemetry

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with OpenTelemetry metrics support.

```bash
pip install "activegraph[opentelemetry]"
```

--------------------------------

### Runtime Initialization in v0.8+

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/cookbook/migration-from-v0-7.md

Examples of initializing the Runtime in v0.8 and later, demonstrating support for file paths and connection URLs for SQLite and PostgreSQL.

```python
# v0.8+:
rt = Runtime(graph, persist_to="/path/to/run.db")           # still works
rt = Runtime(graph, store=SQLiteEventStore("/path/to/run.db"))
rt = Runtime(graph, store=PostgresEventStore("postgres://host/db"))
```

--------------------------------

### Install Active Graph Core

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs the core Active Graph runtime with SQLite store and Diligence pack.

```bash
pip install activegraph
```

--------------------------------

### Install Active Graph with Postgres Store

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with a Postgres-backed event store.

```bash
pip install "activegraph[postgres]"
```

--------------------------------

### Replay Command Example

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/operating-in-production.md

Shows how to use the 'replay' command to rebuild the graph and print a summary of the run.

```bash
activegraph replay sqlite:///run.db --run-id run_01J...
```

--------------------------------

### Activegraph CLI Help and Version

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

Commands to display help documentation for all subcommands or the installed version of activegraph.

```bash
activegraph --help
```

```bash
activegraph --version
```

--------------------------------

### Inspect Command Examples

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/operating-in-production.md

Demonstrates how to use the 'inspect' command with different options, including specifying a run ID, tailing events, and outputting as JSON.

```bash
activegraph inspect sqlite:///run.db
activegraph inspect postgres://localhost/agdb --run-id run_01J... --tail 50 --json
```

--------------------------------

### Install Active Graph with LLM Extras

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/llm-providers.md

Install the necessary extras for Active Graph to use specific LLM providers. Use '[anthropic]', '[openai]', or '[llm]' for both.

```bash
pip install "activegraph[anthropic]"   # AnthropicProvider only
pip install "activegraph[openai]"      # OpenAIProvider only
pip install "activegraph[llm]"         # both providers
```

--------------------------------

### Install Active Graph with OpenAI Provider

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with support for the OpenAI LLM provider and tiktoken.

```bash
pip install "activegraph[openai]"
```

--------------------------------

### Install Active Graph with LLM Providers

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with support for both Anthropic and OpenAI LLM providers.

```bash
pip install "activegraph[llm]"
```

--------------------------------

### Connection URL for PostgreSQL

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

Example of a connection URL for PostgreSQL databases. The 'postgres://' scheme is also accepted.

```bash
postgres://user:pass@host:port/dbname    # also accepted: postgresql://
```

--------------------------------

### Connection URLs for SQLite

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

Examples of connection URLs for SQLite databases. Note the difference between relative (three slashes) and absolute (four slashes) paths.

```bash
sqlite:///relative/path/to/run.db        # three slashes — relative
```

```bash
sqlite:////absolute/path/to/run.db       # four slashes — absolute
```

--------------------------------

### Scaffold a new pack package

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

Use this command to create a new pack package skeleton. It generates all necessary files for authoring a pack, including configuration, stubs, examples, and tests. After installation, the pack becomes discoverable by ActiveGraph.

```bash
activegraph pack new <name> [--output-dir <path>]
```

--------------------------------

### Example: Diligence with Tools

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Runnable end-to-end demo script for performing diligence operations with the aid of external tools. Shows how to integrate tools into the diligence process.

```python
examples/diligence_with_tools.py
```

--------------------------------

### Example ObjectType declarations in Diligence pack

Source: https://github.com/yoheinakajima/activegraph/blob/main/CONTRACT.md

Provides an example of object type declarations within the Diligence pack, emphasizing that these are example ontologies and not framework base types.

```python
ObjectType
```

--------------------------------

### Example: Resume and Fork Workflow

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Runnable end-to-end demo script demonstrating how to resume and fork operations within the ActiveGraph framework. Illustrates state management and branching.

```python
examples/resume_and_fork.py
```

--------------------------------

### Check Activegraph Version

Source: https://github.com/yoheinakajima/activegraph/blob/main/examples/quickstart_session.txt

Verify the installed Activegraph version. This command confirms a successful installation.

```bash
$ activegraph --version
> activegraph 1.0.0
```

--------------------------------

### Check Pack Installation

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/pack-not-found-error.md

Use this command to verify if a specific pack distribution is installed in your environment.

```bash
pip show <pack-distribution-name>
```

--------------------------------

### Using RecordedLLMProvider with OpenAIProvider

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/llm-providers.md

Instantiate OpenAIProvider and wrap it with RecordingLLMProvider to enable fixture-backed recording. Fixtures are stored in the specified directory.

```python
from activegraph.llm import RecordingLLMProvider, OpenAIProvider

inner = OpenAIProvider()
provider = RecordingLLMProvider(inner, fixtures_dir="tests/fixtures/llm")
```

--------------------------------

### Configure Pack Entry Point

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/pack-not-found-error.md

Example TOML configuration for declaring a pack's entry point in `pyproject.toml`. Ensure the `your_pack_module:pack` format correctly points to the Pack instance.

```toml
[project.entry-points."activegraph.packs"]
your_pack = "your_pack_module:pack"
```

--------------------------------

### UnsupportedPatternError Example

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/unsupported-pattern-error.md

This example shows the structure of an UnsupportedPatternError when a pattern does not parse due to an unexpected character.

```text
UnsupportedPatternError: pattern does not parse: unexpected character at position 17

What failed:
  While parsing the pattern: unexpected character at position 17.
    at: '@'
```

--------------------------------

### Start Interactive Behavior Creation

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/quickstart.md

Use this command to initiate an interactive session for creating a new behavior. It scaffolds a starter Python file and prompts for edits.

```bash
activegraph quickstart --interactive
```

--------------------------------

### List installed packs

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/cli.md

This command displays a list of all installed packs that ActiveGraph has discovered. Each line shows the pack's name, version, and distribution name. This is useful for verifying pack installations and understanding the available packs.

```bash
activegraph pack list
```

--------------------------------

### Install Active Graph with Anthropic Provider

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Installs Active Graph with support for the Anthropic LLM provider only.

```bash
pip install "activegraph[anthropic]"
```

--------------------------------

### Example of unsupported OR in WHERE clause

Source: https://github.com/yoheinakajima/activegraph/blob/main/tests/snapshots/errors/unsupported_pattern__or_in_where.txt

This example demonstrates the pattern that triggers the UnsupportedPatternError due to the use of the OR operator in a WHERE clause.

```cypher
WHERE c.confidence > 0.7 OR c.severity = 'high'
```

--------------------------------

### Example: BabyAGI Autonomous Agent Loop

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Runnable end-to-end demo script rebuilding BabyAGI's autonomous agent loop using three reactive behaviors over a shared graph. Illustrates a complex agent architecture.

```python
examples/babyagi.py
```

--------------------------------

### Example Pack Structure and Initialization

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/authoring-packs.md

Defines a pack's core components including settings, object types, and behaviors, and initializes the pack object. This is the main file for a pack package.

```python
from pathlib import Path
from pydantic import BaseModel, Field
from activegraph.packs import (
    Pack, ObjectType, RelationType, PackPolicy,
    behavior, llm_behavior, tool,
    load_prompts_from_dir,
)

class MyPackSettings(BaseModel):
    threshold: float = 0.5

class Insight(BaseModel):
    text: str
    confidence: float = Field(ge=0.0, le=1.0)

@llm_behavior(
    name="insight_extractor",
    on=["object.created"],
    where={"object.type": "document"},
    output_schema=Insight,
)
def insight_extractor(event, graph, ctx, out, *, settings: MyPackSettings):
    if out.confidence >= settings.threshold:
        graph.add_object("insight", out.model_dump())

pack = Pack(
    name="my_pack",
    version="0.1.0",
    description="Extracts insights from documents.",
    object_types=[ObjectType(name="insight", schema=Insight)],
    behaviors=[insight_extractor],
    prompts=load_prompts_from_dir(Path(__file__).parent / "prompts"),
    settings_schema=MyPackSettings,
)
```

--------------------------------

### Example: Operating a Run

Source: https://github.com/yoheinakajima/activegraph/blob/main/README.md

Runnable end-to-end demo script for operating a specific run within the ActiveGraph system. Demonstrates control and management of execution cycles.

```python
examples/operate_a_run.py
```

--------------------------------

### Correct PostgresEventStore Initialization

Source: https://github.com/yoheinakajima/activegraph/blob/main/tests/snapshots/errors/invalid_argument_type__postgres_target.txt

Demonstrates the correct ways to initialize PostgresEventStore with a valid target. Use a postgres:// URL string, a psycopg.Connection, or a psycopg_pool.ConnectionPool.

```python
PostgresEventStore('postgres://host/dbname', run_id=...)
```

```python
PostgresEventStore(my_psycopg_connection, run_id=...)
```

```python
PostgresEventStore(my_connection_pool, run_id=...)
```

--------------------------------

### LLM Schema Violation Example (Instance)

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/llm-behavior-error.md

An example of a correct LLM response that provides an instance conforming to the expected JSON schema.

```json
{"claims": [{"speaker": "...", "statement": "...", "confidence": 0.9}]}
```

--------------------------------

### Loading a Pack with Tools

Source: https://github.com/yoheinakajima/activegraph/blob/main/tests/snapshots/errors/missing_tool.txt

Load a pack that contains the necessary tools for your LLM behaviors. This is an alternative to manually registering individual tools.

```python
rt.load_pack(my_pack)
```

--------------------------------

### LLM Schema Violation Example (Schema)

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/llm-behavior-error.md

An example of an LLM response that incorrectly returns the JSON schema definition itself instead of an instance conforming to the schema.

```json
{
  "type": "object",
  "properties": {"claims": {"type": "array", ...}},
  "required": ["claims"]
}
```

--------------------------------

### Pack Entry Point Configuration

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/guides/authoring-packs.md

Configures the pack's entry point in the pyproject.toml file, allowing ActiveGraph to discover and load the pack.

```toml
[project.entry-points."activegraph.packs"]
my-pack = "my_pack:pack"
```

--------------------------------

### Scaffolded Behavior File in Python

Source: https://github.com/yoheinakajima/activegraph/blob/main/examples/quickstart_session.txt

This Python code represents a scaffolded behavior file created by the interactive quickstart. It includes the necessary import, decorator, and function definition for a custom behavior, with a placeholder for specific logic.

```python
from activegraph import behavior

@behavior(name="growth_flagger", on=["object.created"],
            where={"object.type": "claim"})
def growth_flagger(event, graph, ctx):
    """Flag claims that mention revenue growth above 25%."""
    text = event.payload["object"]["data"].get("text", "")
    # TODO: parse the text for a growth figure and emit if > 25%.
    pass
```

--------------------------------

### ReplayDivergenceError Explanation Example

Source: https://github.com/yoheinakajima/activegraph/blob/main/CONTRACT.md

This example illustrates the 'invariant-protection' voice principle by explaining why a replay cache mismatch occurs, focusing on the protected audit trail invariant rather than the technical mechanism.

```text
The replay cache keys on the full prompt hash, so any change to an
LLM behavior's code, a prompt template, a system message, or a tool's
input arguments produces a mismatch. The framework refuses to silently
substitute a stale cached response under a new prompt — that would
break the audit trail the cache is designed to preserve.
```

--------------------------------

### Override Prompt Template for Schema Violations

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/llm-behavior-error.md

Customize the prompt template for an LLM behavior to include a synthesized example response, helping to prevent schema echo errors. This is useful when automatic example generation is insufficient.

```python
from activegraph.behaviors import llm_behavior

# Assuming ClaimList is a defined Pydantic model or similar schema
# class ClaimList: ...

@llm_behavior(
    output_schema=ClaimList,
    prompt_template=(
        "{system}\n\n"
        "{view}\n\n"
        "Example response (this is the shape — substitute real values):\n"
        '{{"claims": [{{"speaker": "CFO", "statement": "Revenue grew 28%.", ' 
        '"confidence": 0.92}}]}}\n\n'
        "{event}\n\n"
        "{instruction}"
    ),
)
def extract_claims(event, graph, ctx, llm_output): ...

```

--------------------------------

### Migrate and Fork to SQLite

Source: https://github.com/yoheinakajima/activegraph/blob/main/docs/reference/errors/incompatible-runtime-state.md

Migrate the current run to a SQLite store before forking. This is necessary because `runtime.fork()` requires a SQLite-backed runtime.

```bash
activegraph migrate --from <current-url> --to sqlite:///fork-source.db
activegraph fork sqlite:///fork-source.db --run-id <run> --at-event <evt>
```

--------------------------------

### Inspecting Declared Schema Example

Source: https://github.com/yoheinakajima/activegraph/blob/main/CONTRACT.md

Example demonstrating how to inspect a pack's declared schema to debug schema validation errors. This is useful for understanding why an 'add_object' operation might fail due to incorrect field types.

```python
# p.object_types-style introspection
```

--------------------------------

### Example of Pack Schema Violation: Relation Target

Source: https://github.com/yoheinakajima/activegraph/blob/main/tests/snapshots/errors/pack_schema_violation__relation_target.txt

This example demonstrates the specific call that triggers the PackSchemaViolation error due to an incorrect relation target type. The error message explains that the 'supports' relation type, declared in the 'diligence' pack, only allows 'evidence' as a target type, but 'risk' was provided.

```python
graph.add_relation(source, target, 'supports')
```
Tokens:
Raw