AI-Powered Graph Analytics Platform - Experimental

Autonomous AI agents transform business requirements into graph insights

Transform business requirements into actionable graph analytics insights with AI-powered automation. Choose between a traditional workflow orchestrator for full control or an autonomous agentic system for hands-off execution. From requirements documents to intelligence reports in minutes, not weeks.

Key Features

Three Workflow Modes

graph LR
    A[Choose Your Workflow Mode]
    
    A --> B[Traditional<br/>Orchestrator<br/>Step-by-step control]
    A --> C[Agentic<br/>Workflow<br/>Autonomous AI<br/>+ Vertical + Catalog]
    A --> D[ Parallel Agentic<br/>40-60% Faster<br/>Best Performance<br/>+ Vertical + Catalog]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style C fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style D fill:#fff9c4,stroke:#f57f17,stroke-width:3px

Traditional Orchestrator: Step-by-step control, easy to understand and debug
Agentic System: Autonomous AI agents with self-healing and intelligent routing
** Parallel Agentic** (v3.1.0): All benefits of agentic PLUS 40-60% faster execution
Use the approach that fits your needs - all are production-ready

Complete AI-Powered Pipeline

Requirements (PDF/DOCX/Text) → Schema Analysis → Use Cases → Templates → Execution → Intelligence Reports
LLM-powered decision making at every step
Algorithm-aware collection selection (WCC excludes satellites, PageRank uses full graph)
Fully automated or manually controlled - your choice

Production Ready

Real ArangoDB AMP cluster integration
Graph Analytics Engine (GAE) support
Multiple LLM providers (OpenAI, Anthropic, Gemini)
Enterprise-grade error handling and checkpointing

Intelligent Output

Actionable intelligence reports with business context
Interactive HTML reports with embedded Plotly charts
Insights with confidence scores and supporting evidence
Prioritized recommendations with effort/impact estimates
Multiple formats (Markdown, JSON, HTML, Text)

Workspace UI

A point-and-click surface over the same engine, for people who will not drive it from Python.

Per-project asset explorer: connections, graph profiles, requirements, documents, runs, reports
Operational DAG with live status, retry, and cooperative cancel
Dynamic reports with interactive Plotly charts, exportable to HTML/Markdown
Requirements lifecycle: upload a BRD → promote extracted requirements to a draft → approve
Light/dark themes, light by default
See Product UI / Workspace

Analysis Catalog (NEW v3.2.0)

Comprehensive tracking system for all analysis executions with complete lineage and time-series capabilities.

Core Features:

Execution Tracking: Every analysis run with algorithm, parameters, results, and performance metrics
Complete Lineage: Full chain tracking from Requirements → Use Cases → Templates → Executions
Time-Series Analysis: Track graph evolution over time with epochs (e.g., weekly/monthly snapshots)
Impact Analysis: Understand what changes when requirements change
Performance Comparison: Compare algorithm performance across runs and configurations
Universal Support: Works seamlessly with all three workflow modes (Traditional, Agentic, Parallel)

Data Model:

5 ArangoDB collections with optimized indexes
Star schema design for fast queries
Complete foreign key relationships for lineage
Flexible metadata storage

Use Cases:

Track PageRank changes as your graph evolves
Compare algorithm performance across different configurations
Audit which analyses have been run and when
Understand the impact of requirement changes
Generate time-series reports on graph metrics

Documentation:

Quick Start Guide
Complete Graph Schema
API Reference
Custom Industry Verticals Quick Start (generate per-project verticals; supports industry="auto")

Quick Start

Installation

# Clone repository
git clone https://github.com/ArthurKeen/graph-analytics-ai.git
cd graph-analytics-ai

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your credentials

Configuration

Create a .env file:

# ArangoDB Configuration
ARANGO_ENDPOINT=https://your-cluster.arangodb.cloud:8529
ARANGO_DATABASE=your_database
ARANGO_USER=root
ARANGO_PASSWORD=your_password

# For GAE (ArangoDB Managed Platform)
GAE_DEPLOYMENT_MODE=amp
ARANGO_GRAPH_API_KEY_ID=your_api_key_id
ARANGO_GRAPH_API_KEY_SECRET=your_api_key_secret

# LLM Configuration (choose one)
LLM_PROVIDER=openai  # or anthropic, gemini

# OpenAI
OPENAI_API_KEY=your_openai_key
OPENAI_MODEL=gpt-4

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key
ANTHROPIC_MODEL=claude-3-sonnet-20240229

# Google Gemini
GOOGLE_API_KEY=your_google_key
GEMINI_MODEL=gemini-pro

Run Your First Workflow

The platform offers three ways to run analytics workflows, each suited for different use cases:

Traditional Workflow - Step-by-step control with explicit orchestration. Best for learning the platform, debugging, or building custom pipelines.
Agentic Workflow - Autonomous AI agents handle everything automatically. Best for production deployments and hands-off automation.
Parallel Agentic Workflow - Same autonomous execution but 40-60% faster with parallel processing. Best for performance-critical applications.

Choose the approach that fits your needs:

Option 1: Traditional Workflow (Recommended for learning)

from graph_analytics_ai.ai.workflow import WorkflowOrchestrator

# Initialize orchestrator
orchestrator = WorkflowOrchestrator(graph_name="your_graph")

# Run complete workflow with full control
result = orchestrator.run_complete_workflow(
    input_files=["requirements.pdf"]
)

# Access results
print(f"Status: {result.status}")
print(f"Generated {len(result.reports)} reports")

Option 2: Agentic Workflow (Autonomous)

from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

# One-line autonomous execution
runner = AgenticWorkflowRunner(graph_name="your_graph")
state = runner.run()

# AI agents handle everything automatically
print(f"Generated {len(state.reports)} reports")

**Option 3: Parallel Agentic Workflow (Fastest) **

import asyncio
from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

async def main():
    runner = AgenticWorkflowRunner(graph_name="your_graph")
    # 40-60% faster with parallel execution!
    state = await runner.run_async(enable_parallelism=True)
    print(f"Generated {len(state.reports)} reports")

asyncio.run(main())

All workflows execute the same pipeline:

Analyze your graph schema
Extract business requirements
Generate analytics use cases
Create optimized GAE templates
Execute analyses on your cluster
Generate actionable intelligence reports

Choosing Your Workflow Mode

Traditional Orchestrator - Step-by-Step Control

When to use:

Learning the platform
Building custom pipelines
Need granular control
Debugging and testing
Integrating specific steps into existing systems

Complete workflow:

from graph_analytics_ai.ai.workflow import WorkflowOrchestrator

# Initialize with configuration
orchestrator = WorkflowOrchestrator(
    graph_name="ecommerce_graph",
    checkpoint_dir="./checkpoints",
    enable_retry=True
)

# Run complete workflow with checkpointing
result = orchestrator.run_complete_workflow(
    input_files=["requirements.pdf"]
)

# Access detailed results
for step_name, step_result in result.steps.items():
    print(f"{step_name}: {step_result.status}")
    
print(f"\nGenerated {len(result.reports)} reports")

Individual module usage:

# Or use modules individually for custom pipelines
from graph_analytics_ai.ai.schema import SchemaExtractor, SchemaAnalyzer
from graph_analytics_ai.ai.generation import UseCaseGenerator
from graph_analytics_ai.ai.templates import TemplateGenerator
from graph_analytics_ai.ai.execution import AnalysisExecutor
from graph_analytics_ai.ai.reporting import ReportGenerator

# Build your own workflow
extractor = SchemaExtractor(db_connection)
schema = extractor.extract()

analyzer = SchemaAnalyzer()
analysis = analyzer.analyze(schema)

# ... continue with your custom logic

Benefits:

Full control over each step
Easy to understand and debug
Checkpoint and resume support
Integrate into existing pipelines
Explicit error handling

Agentic Workflow - Autonomous Intelligence

When to use:

Production deployments
Hands-off automation
Complex multi-step scenarios
Need self-healing workflows
Want explainable AI decisions

Complete autonomous execution:

from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

# One-line autonomous execution
runner = AgenticWorkflowRunner(graph_name="ecommerce_graph")
state = runner.run()

# Agents handle everything:
# - SchemaAnalyst: Analyzes graph structure
# - RequirementsAnalyst: Extracts business needs
# - UseCaseExpert: Generates analytics use cases
# - TemplateEngineer: Creates GAE configurations
# - ExecutionSpecialist: Runs analyses on cluster
# - ReportingSpecialist: Generates insights

print(f"Workflow Status: {state.status}")
for report in state.reports:
    print(f"\n{report.title}")
    for insight in report.insights:
        print(f"  - {insight.title} (confidence: {insight.confidence:.0%})")

Agent communication example:

[Orchestrator] Starting workflow
[SchemaAnalyst] Extracted: 3 vertex collections, 5 edge collections
[RequirementsAnalyst] Extracted: 1 objective, 3 requirements
[UseCaseExpert] Generated 2 use cases (PageRank, Community Detection)
[TemplateEngineer] Created 2 optimized templates
[ExecutionSpecialist] Completed analyses in 2.8s
[ReportingSpecialist] Generated 2 intelligence reports
[Orchestrator] Workflow complete - Success!

Benefits:

Autonomous decision-making
Self-healing error recovery
Explainable AI (agent messages)
Adaptive workflow routing
Domain expertise per agent
Minimal configuration required

Architecture

Core Pipeline

Both workflow modes execute the same underlying pipeline:

graph TB
    Input[Business Requirements<br/>PDF/DOCX/Text]

    Vertical["Industry Vertical Resolver<br/>Built-in / Project Custom / Auto-generate<br/>Loads domain prompt + patterns<br/>Writes industry_vertical.json (when generated)"]
    
    Schema[Schema Extract<br/>Extract graph structure]
    Req[Requirements<br/>Parse business needs]
    UseCase[Use Cases<br/>Map to algorithms]
    Template[Templates<br/>Generate GAE configs]
    Execute[Execute<br/>Run on ArangoDB GAE]
    Report[Report<br/>Generate insights]

    Catalog[("Analytics Catalog<br/>Epochs + lineage + time-series<br/>Requirements to Use Cases to Templates to Executions")]
    
    Output["Actionable Intelligence Reports<br/>Business insights with confidence scores<br/>Prioritized recommendations<br/>Multiple output formats"]
    
    Input --> Vertical
    Input --> Schema
    Input --> Req
    Schema --> UseCase
    Req --> UseCase
    UseCase --> Template
    Template --> Execute
    Execute --> Report
    Report --> Output

    Req -.->|track_requirements| Catalog
    UseCase -.->|track_use_case| Catalog
    Template -.->|track_template| Catalog
    Execute -.->|track_execution| Catalog
    
    style Input fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Output fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style Vertical fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    style Schema fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style Req fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style UseCase fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Template fill:#e0f2f1,stroke:#00796b,stroke-width:2px
    style Execute fill:#ffe0b2,stroke:#e65100,stroke-width:2px
    style Report fill:#c5e1a5,stroke:#558b2f,stroke-width:2px
    style Catalog fill:#ede7f6,stroke:#4527a0,stroke-width:2px

Workflow Mode Comparison

Traditional Orchestrator

Sequential step execution with checkpointing
Full programmatic control over each phase
Easy to debug and customize
Direct module integration
Perfect for custom pipelines

Agentic System

6 specialized AI agents with domain expertise
Supervisor pattern for intelligent coordination
Self-healing error recovery
Explainable AI decision-making
Autonomous workflow adaptation

Parallel Agentic Workflow (v3.1.0)

All benefits of agentic system PLUS:
40-60% faster execution
Parallel schema + requirements analysis
Concurrent template execution
Simultaneous report generation

Agentic Workflow Architecture

The agentic system uses 6 specialized AI agents coordinated by a supervisor:

graph TB
    subgraph "Agentic Workflow System"
        Orch[Orchestrator Agent<br/>Supervisor Pattern<br/>• Coordinates all agents<br/>• Intelligent routing<br/>• Error recovery]

        Vertical[Industry Vertical Resolver<br/>• Built-in verticals<br/>• Project custom verticals<br/>• Auto-generate if missing<br/>• Provides domain prompt + patterns]
        
        Schema[Schema Analyst<br/>Graph DB Expert<br/>• Extracts structure<br/>• Analyzes patterns]
        
        Req[Requirements Analyst<br/>Business Expert<br/>• Parses documents<br/>• Extracts needs]
        
        UseCase[Use Case Expert<br/>Analytics Consultant<br/>• Maps to algorithms<br/>• Prioritizes value]
        
        Template[Template Engineer<br/>Configuration Expert<br/>• Optimizes parameters<br/>• Validates templates]
        
        Exec[Execution Specialist<br/>Operations Expert<br/>• Runs analyses<br/>• Monitors progress]
        
        Report[Reporting Specialist<br/>BI Expert<br/>• Generates insights<br/>• Creates reports]
    end

    Catalog[(Analytics Catalog<br/>Epochs + lineage + time-series)]
    
    Orch --> Vertical
    Orch --> Schema
    Orch --> Req
    Schema --> UseCase
    Req --> UseCase
    UseCase --> Template
    Template --> Exec
    Exec --> Report

    Vertical -.->|domain prompt| Orch
    
    Schema -.->|result| Orch
    Req -.->|result| Orch
    UseCase -.->|result| Orch
    Template -.->|result| Orch
    Exec -.->|result| Orch
    Report -.->|result| Orch

    Orch -.->|create/reuse epoch| Catalog
    Req -.->|track_requirements| Catalog
    UseCase -.->|track_use_case| Catalog
    Template -.->|track_template| Catalog
    Exec -.->|track_execution| Catalog
    
    style Orch fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    style Vertical fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    style Schema fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style Req fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style UseCase fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Template fill:#e0f2f1,stroke:#00796b,stroke-width:2px
    style Exec fill:#ffe0b2,stroke:#e65100,stroke-width:2px
    style Report fill:#c5e1a5,stroke:#558b2f,stroke-width:2px
    style Catalog fill:#ede7f6,stroke:#4527a0,stroke-width:2px

Parallel Execution Architecture (v3.1.0)

40-60% performance improvement through intelligent parallelization:

graph TB
    subgraph Stage0[" Industry Vertical: Auto (built-in/custom/generate)"]
        Vertical[Resolve industry prompt + patterns]
    end

    subgraph Stage1[" Initial Analysis: Parallel (2x speedup)"]
        Schema[Schema Analysis]
        Req[Requirements Extraction]
    end
    
    subgraph Stage2["Use Case Generation: Sequential"]
        UseCase[Use Case Generation]
    end
    
    subgraph Stage3["Template Generation: Sequential"]
        Template[Template Generation]
    end
    
    subgraph Stage4[" Template Execution: Parallel (Nx speedup)"]
        E1[Execute Template 1]
        E2[Execute Template 2]
        E3[Execute Template N...]
    end
    
    subgraph Stage5[" Report Generation: Parallel (Nx speedup)"]
        R1[Generate Report 1]
        R2[Generate Report 2]
        R3[Generate Report N...]
    end

    Catalog[(Analytics Catalog<br/>epoch + lineage)]
    
    Vertical --> Schema
    Vertical --> Req
    Schema --> UseCase
    Req --> UseCase
    UseCase --> Template
    Template --> E1
    Template --> E2
    Template --> E3
    E1 --> R1
    E2 --> R2
    E3 --> R3

    UseCase -.->|track_use_case| Catalog
    Template -.->|track_template| Catalog
    E1 -.->|track_execution| Catalog
    E2 -.->|track_execution| Catalog
    E3 -.->|track_execution| Catalog
    
    style Stage0 fill:#bbdefb,stroke:#1565c0,stroke-width:3px
    style Stage1 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style Stage4 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style Stage5 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
    style Stage2 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Stage3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Catalog fill:#ede7f6,stroke:#4527a0,stroke-width:2px

Performance Gains:

Initial Analysis: Schema + Requirements run in parallel → 2x faster
Template Execution: All templates execute concurrently → Nx faster
Report Generation: All reports generate simultaneously → Nx faster
Overall: 40-60% total time reduction

Usage:

import asyncio
from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

async def main():
    runner = AgenticWorkflowRunner(
        graph_name="your_graph",
        enable_tracing=True  # See performance metrics
    )
    
    # Parallel execution (default)
    state = await runner.run_async(enable_parallelism=True)
    
    # View performance improvements
    runner.print_trace_summary()

asyncio.run(main())

Agent Responsibilities:

Agent	Role	Tools
Orchestrator	Supervisor, routing, error recovery	All agent coordination
Schema Analysis	Extract graph structure	Database queries, LLM analysis
Requirements	Parse business needs	Document parsing, LLM extraction
Use Case	Map needs to algorithms	LLM reasoning, algorithm selection
Template	Generate GAE configurations	Collection selection, parameter optimization
Execution	Run analyses on GAE	GAE API, result validation
Reporting	Generate insights	LLM interpretation, chart generation

Technology Stack

AI & Agent Layer

Layer	Technology	Role
Agent Orchestration	LangGraph	Stateful multi-agent supervisor graph — coordinates 6 specialized agents with conditional routing, self-healing, and parallel execution
LLM Providers	OpenAI / Anthropic / Gemini	Inference at every pipeline step (schema analysis, use-case generation, report synthesis)
Tool Protocol	MCP (Model Context Protocol)	Exposes the platform as callable tools to any MCP-compatible AI host (Claude Desktop, Cursor, etc.)

Infrastructure Layer

Layer	Technology	Role
Graph Database	ArangoDB	Stores the business graph and analytics catalog
Graph Analytics Engine	ArangoDB GAE	Executes algorithms (PageRank, WCC, SCC, Label Propagation, Betweenness) on the cluster
Async Runtime	Python asyncio + aiohttp	Powers parallel agent execution (40-60% speedup)
Database Driver	python-arango	ArangoDB Python client
CLI	Click	Command-line interface (`gaai` + `gaai-mcp`)

CLI Interface

The platform includes a comprehensive CLI supporting both workflow modes:

# Check version
gaai version

# Run traditional workflow (with checkpointing)
gaai run-workflow \
  --database graph_db \
  --graph my_graph \
  --input requirements.pdf \
  --output results/ \
  --checkpoint checkpoints/

# Run agentic workflow (autonomous)
gaai run-workflow \
  --database graph_db \
  --graph my_graph \
  --input requirements.pdf \
  --mode agentic \
  --output results/

# Use individual modules
gaai analyze-schema \
  --database graph_db \
  --output schema.json

gaai parse-requirements \
  --input requirements.pdf \
  --output requirements.json

# Check workflow status
gaai status --checkpoint checkpoint.json

🛠️ CLI Utilities (NEW in v3.0+)

The library now includes reusable command-line utilities for common tasks:

Token Management:

# Get or refresh OASIS token for AMP authentication
python -m graph_analytics_ai.auth.oasis_token_helper

# Check token status
python -m graph_analytics_ai.auth.oasis_token_helper --status

# Force refresh
python -m graph_analytics_ai.auth.oasis_token_helper --refresh

Connection Testing:

# Test and verify database connection
python -m graph_analytics_ai.cli.test_connection

GAE Management:

# List and cleanup GAE engines
python -m graph_analytics_ai.cli.gae_cleanup

Python API:

from graph_analytics_ai.auth import get_or_refresh_token
from graph_analytics_ai.cli.test_connection import test_connection

# Get authentication token
token = get_or_refresh_token()

# Test connection
if test_connection():
    print("Ready to run workflow!")

📖 Full Documentation: CLI Utilities Guide

Product UI / Workspace

The platform ships with a Next.js workspace UI backed by a FastAPI adapter (graph_analytics_ai.product.fastapi_app). Where the library sections above are for driving the pipeline from Python, the workspace is the point-and-click surface over the same engine.

What the workspace gives you

Asset explorer — connection profiles, graph profiles, requirements, source documents, runs, and reports for a customer project, each with its own canvas.
Operational DAG — the agentic run rendered as its canonical steps with live status, retry, and cooperative cancel.
Dynamic reports — report sections plus interactive Plotly charts rendered from stored records, exportable to HTML or Markdown.
Requirements lifecycle — upload a BRD, promote its extracted requirements into a draft version, approve it to supersede the prior active set (FR-15).
Artifact links — a step's detail panel links to what that step produced; clicking a report opens its canvas (FR-37).
Light and dark themes — light by default, with a toggle at the top right whose choice is remembered per device.

The API mirrors those assets and exposes three endpoints that wire the agentic pipeline end to end:

Endpoint	Purpose
`POST /api/runs/{run_id}/start`	Flips the run to RUNNING and dispatches it to the in-process supervisor.
`POST /api/runs/{run_id}/cancel`	Cooperative cancel — stops the run after the current orchestrator step.
`GET /api/runs/{run_id}/status`	Lightweight snapshot (`executor_kind`, supervisor outcome, cancel intent).

Enabling the agentic supervisor

The supervisor is off by default so the API can be used purely as a UI surface in environments without LLM credentials. Enable it for your dev session by either:

# Option 1: env var (recommended for shells/CI)
export AGA_ENABLE_AGENTIC_SUPERVISOR=1

# Option 2: programmatic toggle when constructing the app
from graph_analytics_ai.product.fastapi_app import create_product_fastapi_app
app = create_product_fastapi_app(enable_agentic_supervisor=True)

When enabled, POST /api/runs/{id}/start for an agentic (or parallel_agentic) run will:

Replace any user-supplied step labels with the canonical six-step layout (Schema Analysis → Requirements Extraction → Use Case Generation → Template Generation → Execution → Reporting).
Submit the run to a ThreadPoolExecutor that constructs an AgenticWorkflowRunner per request.
Stream STEP_START / STEP_END / AGENT_ERROR trace events into per-step status updates the UI sees on its next /status poll.
Emit start_workflow_run and execute_workflow audit events.

On startup, the supervisor sweeps any orphan RUNNING rows left over from a previous process (Phase 1's executor is in-process, so an API restart is by definition a death sentence for in-flight runs). On shutdown it signals cancel and drains the worker pool best-effort.

Production note — Phase 1 is single-process and loses in-flight runs on restart. Customer-facing deployments should wait for FR-31b's durable executor migration. See docs/PRD_AGENTIC_GRAPH_ANALYTICS_UI.md §FR-31a/Decision 2 for the migration plan.

Running the API + UI locally

The workspace keeps its own metadata database, separate from the graph you are analysing. ARANGO_DATABASE in .env points at the analytics graph (e.g. addtech-knowledge-graph); the product API must be started against the workspace database instead, or it will come up empty:

# Backend (terminal 1) — bypass any sandbox proxy that might block ArangoDB
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy \
    ARANGO_DATABASE=aga_workspace \
    AGA_ENABLE_AGENTIC_SUPERVISOR=1 \
    gaai-product-api serve

# Frontend (terminal 2)
cd frontend && npm run dev

The UI defaults to the API at http://localhost:8000; override with NEXT_PUBLIC_PRODUCT_API_BASE_URL. When it finds a live run in agentic mode it polls /status every ~3 seconds and shows executor

supervisor metadata in a panel above the DAG.

If the UI shows "Failed to fetch. Showing demo data." the API is reachable but rejecting the browser's origin. CORS is allow-listed to localhost/127.0.0.1 on ports 3000 and 3010 only, so a frontend that landed on any other port (Next picks the next free one when 3000 is taken) is blocked. Either free port 3000 or tell the API about the port you got:
AGA_PRODUCT_CORS_ORIGINS="http://localhost:3002,http://127.0.0.1:3002" gaai-product-api serve
The banner at the top of the workspace reads LIVE when it is really talking to the API, and DEMO/ERROR when it has fallen back — check it before concluding the data is wrong.

🔌 MCP Server (NEW)

Expose the platform as an MCP (Model Context Protocol) server so any MCP-compatible AI host — Claude Desktop, Cursor, etc. — can call graph analytics directly as tools.

Installation

pip install ".[mcp]"

Quick Start

# Start the MCP server
gaai-mcp

# Or via module
python -m graph_analytics_ai.mcp

Claude Desktop / Cursor Configuration

Copy this into your mcp_servers.json (see mcp_config.example.json for a full template):

{
  "graph-analytics-ai": {
    "command": "python",
    "args": ["-m", "graph_analytics_ai.mcp"],
    "env": {
      "ARANGO_ENDPOINT": "https://your-cluster:8529",
      "ARANGO_DATABASE": "your_db",
      "ARANGO_USER": "root",
      "ARANGO_PASSWORD": "...",
      "LLM_PROVIDER": "openai",
      "OPENAI_API_KEY": "..."
    }
  }
}

Available Tools

Group	Tool	Description
Graph	`get_connection_info`	Returns ArangoDB endpoint + database (no password)
	`list_graphs`	Lists named graphs in the configured database
	`describe_graph`	Vertex/edge collection definitions for a graph
	`analyze_schema`	Full schema extraction + LLM analysis
Workflow	`start_workflow`	Launch an agentic workflow; returns `job_id` immediately
	`get_workflow_status`	Poll status of a running workflow by `job_id`
	`list_workflow_jobs`	List all jobs in the current server session
Catalog	`list_epochs`	Recent analysis epochs
	`get_epoch`	Full detail for one epoch
	`query_executions`	Paginated execution search with filters
	`get_lineage`	Complete lineage chain for an execution
	`get_catalog_stats`	Summary statistics
GAE	`list_gae_engines`	Active GAE engine instances
	`run_analysis`	Run a single algorithm directly (no AI planning needed)
	`cleanup_engines`	Remove idle/stale engines (dry-run by default)

Interactive Testing (MCP Inspector)

# Inspector launches a browser UI at http://localhost:5173
mcp dev graph_analytics_ai/mcp/server.py

Examples

Example 1: Complete Workflow (Traditional)

from graph_analytics_ai.ai.workflow import WorkflowOrchestrator

# Initialize orchestrator
orchestrator = WorkflowOrchestrator(
    graph_name="ecommerce_graph",
    checkpoint_dir="./checkpoints"
)

# Run complete workflow with full control
result = orchestrator.run_complete_workflow(
    input_files=["business_requirements.pdf"]
)

# Check status and access results
if result.success:
    print(f"Workflow completed successfully!")
    print(f"Generated {len(result.reports)} reports")
    
    for report in result.reports:
        print(f"\n{report.title}")
        print(f"  Insights: {len(report.insights)}")
        print(f"  Recommendations: {len(report.recommendations)}")
else:
    print(f"Workflow failed: {result.error}")

Example 2: E-commerce Analytics (Agentic)

from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

# One-line autonomous execution
runner = AgenticWorkflowRunner(graph_name="ecommerce_graph")
state = runner.run()

# Results: Customer influence analysis, product recommendations, etc.
for report in state.reports:
    print(f"\n{report.title}")
    for insight in report.insights:
        print(f"  - {insight.title} (confidence: {insight.confidence*100:.0f}%)")

Example 3: Custom Module Integration

Build your own pipeline using individual modules:

from graph_analytics_ai.db_connection import get_db_connection
from graph_analytics_ai.ai.schema import SchemaExtractor, SchemaAnalyzer
from graph_analytics_ai.ai.generation import UseCaseGenerator
from graph_analytics_ai.ai.templates import TemplateGenerator
from graph_analytics_ai.ai.execution import AnalysisExecutor
from graph_analytics_ai.ai.reporting import ReportGenerator

# Step 1: Extract schema
db = get_db_connection()
extractor = SchemaExtractor(db)
schema = extractor.extract()

# Step 2: Analyze schema
analyzer = SchemaAnalyzer()
analysis = analyzer.analyze(schema)

# Step 3: Create custom requirements
from graph_analytics_ai.ai.documents.models import (
    ExtractedRequirements, Objective, Priority
)

requirements = ExtractedRequirements(
    domain="Social Network",
    summary="Find key influencers",
    objectives=[
        Objective(
            id="OBJ-001",
            title="Identify Top Influencers",
            priority=Priority.CRITICAL
        )
    ]
)

# Step 4: Generate use cases
uc_generator = UseCaseGenerator()
use_cases = uc_generator.generate(requirements, analysis)

# Step 5: Generate templates
template_gen = TemplateGenerator(graph_name="social_network")
templates = template_gen.generate_templates(use_cases, schema, analysis)

# Step 6: Execute and report
executor = AnalysisExecutor()
report_gen = ReportGenerator()

for template in templates:
    result = executor.execute_template(template, wait=True)
    if result.success:
        report = report_gen.generate_report(result)
        print(f"\n{report.title}")
        print(report.summary)

Example 5: Report Generation

from graph_analytics_ai.ai.reporting import ReportGenerator, ReportFormat

generator = ReportGenerator()
report = generator.generate_report(execution_result)

# Export in different formats
markdown = generator.format_report(report, ReportFormat.MARKDOWN)
json_output = generator.format_report(report, ReportFormat.JSON)
html = generator.format_report(report, ReportFormat.HTML)

# Save
with open('report.md', 'w') as f:
    f.write(markdown)

Example 6: Interactive HTML Reports with Charts NEW

from graph_analytics_ai.ai.reporting import (
    ReportGenerator, 
    HTMLReportFormatter,
    is_plotly_available
)

# Check if charts are available
if is_plotly_available():
    # Generate report with interactive charts
    generator = ReportGenerator(enable_charts=True)
    report = generator.generate_report(execution_result, context={
        "use_case": {"title": "Network Analysis"},
        "requirements": {"domain": "social network"}
    })
    
    # Format as HTML with embedded Plotly charts
    html_formatter = HTMLReportFormatter()
    charts = report.metadata.get('charts', {})
    html_content = html_formatter.format_report(report, charts=charts)
    
    # Save interactive HTML report
    with open('report.html', 'w') as f:
        f.write(html_content)
    
    print(f" Generated report with {len(charts)} interactive charts!")
    # Charts include:
    # - Top influencers/components bar charts
    # - Distribution histograms (log-scale)
    # - Connectivity pie charts
    # - Fully interactive (hover, zoom, pan)
else:
    print("Install plotly for interactive charts: pip install plotly")

Chart Types by Algorithm:

PageRank: Top influencers, rank distribution, cumulative influence
WCC: Component sizes, distribution, connectivity overview
Betweenness: Bridge nodes, centrality distribution
Label Propagation: Community sizes, distribution

See Interactive Report Generation Guide for details.

Advanced Configuration

Custom LLM Configuration

from graph_analytics_ai.ai.llm import create_llm_provider

# Custom provider
provider = create_llm_provider(
    provider_type="openai",
    model="gpt-4-turbo-preview",
    temperature=0.7,
    max_tokens=2000
)

# Use in agents
from graph_analytics_ai.ai.agents import AgenticWorkflowRunner
runner = AgenticWorkflowRunner(llm_provider=provider)

Custom Agent Configuration

from graph_analytics_ai.ai.agents import OrchestratorAgent
from graph_analytics_ai.ai.agents.specialized import SchemaAnalysisAgent

# Create custom agents
schema_agent = SchemaAnalysisAgent(
    llm_provider=provider,
    db_connection=db
)

# Build custom orchestrator
orchestrator = OrchestratorAgent(
    llm_provider=provider,
    agents={"SchemaAnalyst": schema_agent, ...}
)

Workflow Customization

from graph_analytics_ai.ai.workflow import WorkflowOrchestrator

orchestrator = WorkflowOrchestrator(
    llm_provider=provider,
    db_connection=db,
    checkpoint_dir="./checkpoints",
    enable_retry=True,
    max_retries=3
)

result = orchestrator.run_complete_workflow(
    input_files=["requirements.pdf"],
    graph_name="my_graph"
)

Algorithm-Specific Collection Selection

Different algorithms require different graph subsets. The platform automatically selects appropriate collections:

from graph_analytics_ai.ai.templates import TemplateGenerator

# Specify which collections are satellite/core
generator = TemplateGenerator(
    graph_name="my_graph",
    satellite_collections=["metadata", "configs", "lookup_tables"],
    core_collections=["users", "products", "orders"]
)

# WCC will exclude satellites (find core components)
# PageRank will include everything (full graph importance)
# Betweenness will include everything (accurate centrality)
templates = generator.generate_templates(use_cases, schema)

# Check what was selected
for template in templates:
    print(f"{template.name}: {template.config.vertex_collections}")
    print(f"Reasoning: {template.metadata['collection_selection_reasoning']}")

See the Collection Selection Guide for details.

Example Output

Intelligence Report

# Analysis Report: Customer Influence Analysis

*Generated: 2025-12-12 18:00:00*

## Executive Summary

Analysis of 500 customers using PageRank algorithm. 
Identified 50 high-influence customers (top 10%).
Generated 3 key insights and 2 high-priority recommendations.

## Key Insights

### 1. Top Influencers Identified (Confidence: 95%)

Discovered 50 customers with exceptional influence scores.
Average score: 0.0234. Top influencer: customer_42 (0.0456).

**Business Impact:** Focus engagement campaigns on these 50 
customers for maximum ROI. Estimated 25% increase in conversion.

### 2. Power-Law Distribution Detected (Confidence: 88%)

Influence follows power-law: top 20% accounts for 80% of 
total influence.

**Business Impact:** Implement tiered engagement strategy.
Optimize resources by focusing on high-value segments.

## Recommendations

### High Priority

**1. Launch VIP Program**
Create exclusive program for top 50 influencers.
- Priority: High
- Effort: Medium  
- Expected Impact: 25% engagement increase

**2. Monitor Influence Changes**
Track influence scores monthly to detect shifts.
- Priority: High
- Effort: Low
- Expected Impact: Early trend detection, proactive engagement

🧪 Testing

# Run all tests
pytest

# Run specific test suite
pytest tests/unit/ai/agents/

# Run with coverage
pytest --cov=graph_analytics_ai tests/

# Run integration tests (requires cluster)
pytest tests/integration/

Performance

Parallel Execution Performance (v3.1.0)

** 40-60% faster** with parallel agentic workflow:

gantt
    title Workflow Execution Time Comparison
    dateFormat X
    axisFormat %s
    
    section Sequential v3.0
    Schema Analysis       :done, 0, 20s
    Requirements          :done, 20s, 40s
    Use Case Generation   :done, 40s, 65s
    Template Generation   :done, 65s, 85s
    Execute Template 1    :done, 85s, 100s
    Execute Template 2    :done, 100s, 115s
    Execute Template 3    :done, 115s, 130s
    Execute Template 4    :done, 130s, 145s
    Execute Template 5    :done, 145s, 160s
    Report 1              :done, 160s, 167s
    Report 2              :done, 167s, 174s
    Report 3              :done, 174s, 181s
    Report 4              :done, 181s, 188s
    Report 5              :done, 188s, 195s
    
    section Parallel v3.1
    Schema Analysis       :done, p1, 0, 22s
    Requirements          :done, p2, 0, 22s
    Use Case Generation   :done, 22s, 47s
    Template Generation   :done, 47s, 67s
    Execute (all 5)       :crit, 67s, 87s
    Reports (all 5)       :crit, 87s, 97s

Performance Comparison (5 templates, 5 reports):

Metric	Sequential v3.0	Parallel v3.1	Improvement
Phase 1 (Schema + Reqs)	40s	22s	45% faster
Phase 4 (5 Executions)	75s	20s	73% faster
Phase 5 (5 Reports)	35s	10s	71% faster
Total Time	195s	97s	50% faster
LLM Calls	15	15	Same
Cost	$0.045	$0.045	Same

Key Benefits:

Faster results: Get insights in half the time
Same cost: No additional LLM or compute costs
Same quality: Identical outputs, just faster
Scalable: Benefit increases with more templates

Traditional Workflow Benchmarks

Workflow	Documents	Templates	Execution	Total Time
Small	1K nodes	2	2.5s	~8s
Medium	10K nodes	5	12s	~25s
Large	100K nodes	10	45s	~90s

Benchmarks on ArangoDB AMP e16 engine

Scalability

Handles graphs up to 10M+ nodes
Parallel agent execution (v3.1.0)
Batch analysis support
Checkpointing for long-running workflows

Enable Parallel Execution:

import asyncio
from graph_analytics_ai.ai.agents import AgenticWorkflowRunner

async def main():
    runner = AgenticWorkflowRunner(enable_tracing=True)
    state = await runner.run_async(enable_parallelism=True)
    
    # View performance metrics
    runner.print_trace_summary()

asyncio.run(main())

Development

Project Structure

graph-analytics-ai/
├── graph_analytics_ai/          # Main package
│   ├── ai/                       # AI components
│   │   ├── agents/              # Agentic workflow (Phase 10)
│   │   │   ├── base.py          # Agent framework
│   │   │   ├── orchestrator.py  # Supervisor agent
│   │   │   ├── specialized.py   # Domain agents
│   │   │   └── runner.py        # Workflow runner
│   │   ├── llm/                 # LLM abstraction (Phase 1)
│   │   ├── schema/              # Schema analysis (Phase 2)
│   │   ├── documents/           # Document processing (Phase 3)
│   │   ├── prd/                 # PRD generation (Phase 4)
│   │   ├── generation/          # Use case generation (Phase 5)
│   │   ├── workflow/            # Workflow orchestration (Phase 6)
│   │   ├── templates/           # Template generation (Phase 7)
│   │   ├── execution/           # Analysis execution (Phase 8)
│   │   └── reporting/           # Report generation (Phase 9)
│   ├── db_connection.py         # Database utilities
│   └── cli.py                   # CLI interface
├── tests/                       # Test suite
├── examples/                    # Example scripts
├── docs/                        # Documentation
└── scripts/                     # Utility scripts

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Coding Standards

PEP 8 compliance
Type hints for all functions
Docstrings for all public APIs
Tests for all new features
90%+ test coverage

Documentation

Reference

Documentation index - Everything below, organised
Product PRD - Source of truth for what the workspace must do
API Reference - Result management, collection selection, orchestration
Workflow Guide - Workflow details
Agentic Workflow - Agent system and autonomous execution
Parallel Execution Guide - Async/parallel workflow (40-60% faster!)
Custom Verticals Quick Start - Per-project industry verticals
Examples - Code examples

Explaining it to other people

One-pager - What it is, who it is for, what it costs to try
Medium article draft - Long-form narrative for a non-graph audience
Intro deck - Slides (editable PowerPoint)

Platform Features by Phase

Phase	Feature	Status
1	LLM Foundation	Complete
2	Schema Analysis	Complete
3	Document Processing	Complete
4	PRD Generation	Complete
5	Use Case Generation	Complete
6	Workflow Orchestration	Complete
7	Template Generation	Complete
8	Analysis Execution	Complete
9	Report Generation	Complete
10	Agentic Workflow	Complete

Progress: 100% (10/10 phases)

Use Cases

1. E-commerce

Customer influence analysis
Product recommendation optimization
Purchase pattern detection
Churn prediction

2. Social Networks

Influencer identification
Community detection
Content propagation analysis
Network growth modeling

3. Fraud Detection

Transaction network analysis
Anomaly detection
Risk scoring
Pattern recognition

4. Knowledge Graphs

Entity relationship analysis
Path discovery
Semantic similarity
Knowledge extraction

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

ArangoDB - Graph database and GAE platform
OpenAI - GPT models
Anthropic - Claude models
Google - Gemini models

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@graph-analytics-ai.com

Roadmap

Completed

Future Enhancements

Statistics

~15,000+ lines of production code
2 workflow modes (traditional orchestrator + agentic)
6 specialized AI agents (for agentic mode)
7 core modules (schema, documents, PRD, use cases, templates, execution, reporting)
10 complete implementation phases
90%+ test coverage
4 LLM providers supported (OpenAI, Anthropic, Gemini, + custom)
Multiple output formats (Markdown, JSON, HTML, Text)

Star History

If you find this project useful, please consider giving it a star!

Built with by the Graph Analytics AI team

Version 3.0.0 | 100% Complete | Production Ready

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github		.github
docs		docs
examples		examples
frontend		frontend
graph_analytics_ai		graph_analytics_ai
scripts		scripts
templates		templates
tests		tests
workflow_output		workflow_output
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SUPPORTED_INDUSTRIES.md		SUPPORTED_INDUSTRIES.md
ecommerce_pagerank_report.html		ecommerce_pagerank_report.html
mcp_config.example.json		mcp_config.example.json
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
run_agentic_workflow.py		run_agentic_workflow.py
sample_household_report.html		sample_household_report.html
setup.py		setup.py
test_connection.py		test_connection.py
test_custom_vertical.py		test_custom_vertical.py
validate_tests.py		validate_tests.py

Latest commit

History

Folders and files

Repository files navigation

AI-Powered Graph Analytics Platform - Experimental

Key Features

Quick Start

Installation

Configuration

Run Your First Workflow

Choosing Your Workflow Mode

Traditional Orchestrator - Step-by-Step Control

Agentic Workflow - Autonomous Intelligence

Architecture

Core Pipeline

Workflow Mode Comparison

Agentic Workflow Architecture

Parallel Execution Architecture (v3.1.0)

Technology Stack

CLI Interface

🛠️ CLI Utilities (NEW in v3.0+)

Product UI / Workspace

Enabling the agentic supervisor

Running the API + UI locally

🔌 MCP Server (NEW)

Installation

Quick Start

Claude Desktop / Cursor Configuration

Available Tools

Interactive Testing (MCP Inspector)

Examples

Example 1: Complete Workflow (Traditional)

Example 2: E-commerce Analytics (Agentic)

Example 3: Custom Module Integration

Example 5: Report Generation

Example 6: Interactive HTML Reports with Charts NEW

Advanced Configuration

Custom LLM Configuration

Custom Agent Configuration

Workflow Customization

Algorithm-Specific Collection Selection

Example Output

Intelligence Report

🧪 Testing

Performance

Parallel Execution Performance (v3.1.0)

Traditional Workflow Benchmarks

Scalability

Development

Project Structure

Contributing

Coding Standards

Documentation

Platform Features by Phase

Use Cases

1. E-commerce

2. Social Networks

3. Fraud Detection

4. Knowledge Graphs

License

Acknowledgments

Support

Roadmap

Completed

Future Enhancements

Statistics

Star History

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages