Skip to content

README.md

Latest commit

 

History

History
246 lines (169 loc) · 6.76 KB

README.md

File metadata and controls

246 lines (169 loc) · 6.76 KB

RoboSystems Examples

Comprehensive examples demonstrating RoboSystems' graph database capabilities across different domains and use cases.

Quick Start

# Make sure RoboSystems is running
just start

# Run all demos in sequence
just demo

# Or run individual demos
just demo-roboledger
just demo-custom-graph
just demo-sec NVDA 2025

Available Demos

1. SEC Demo - Public Company Financial Data

Query real SEC XBRL financial data from public companies.

Features:

  • Loads SEC 10-K/10-Q filings from EDGAR
  • Processes XBRL financial statements
  • Queries balance sheets, income statements, and cash flows
  • Demonstrates financial fact analysis

Usage:

# Load and query NVIDIA 2025 financials (includes queries)
just demo-sec NVDA 2025

# Load NVIDIA data without running queries
just demo-sec NVDA 2025 true

# Query SEC data with specific examples
just demo-sec-query

# Run all available query examples
just demo-sec-query true

Available Tickers: Any publicly traded US company with SEC filings (e.g., AAPL, MSFT, GOOGL, TSLA, NVDA)

What It Does:

  1. Fetches SEC filing from EDGAR API
  2. Processes XBRL data into graph format
  3. Loads entities, elements, facts, and relationships
  4. Runs example queries on financial data

Location: /examples/sec_demo/

Documentation: See README.md for detailed guide and query examples

2. Custom Graph Demo - Generic Graph Structure

Demonstrates custom schema creation with people, companies, and projects.

Features:

  • Custom node types (Person, Company, Project)
  • Custom relationships (employment, collaboration, participation)
  • Flexible schema definition via JSON
  • Demonstrates generic graph capabilities

Usage:

# Run with new graph (default)
just demo-custom-graph

# Create new user and graph
just demo-custom-graph new-user,new-graph

# Skip verification queries
just demo-custom-graph skip-queries

What It Creates:

  • 50 Person nodes (name, age, email, interests)
  • 10 Company nodes (name, industry, location, size)
  • 15 Project nodes (name, description, status, budget)
  • PERSON_WORKS_FOR_COMPANY relationships (employment)
  • PERSON_WORKS_ON_PROJECT relationships (project teams)
  • COMPANY_SPONSORS_PROJECT relationships (sponsorship)

What It Does:

  1. Sets up user credentials (or reuses existing)
  2. Creates graph with custom schema from schema.json
  3. Generates synthetic graph data
  4. Uploads and ingests via staging tables
  5. Runs example queries (org charts, collaborations, projects)

Location: /examples/custom_graph_demo/

Documentation: See README.md for step-by-step guide

Customization: Edit schema.json to define your own node types and relationships

Credential Management

All demos share a common credential system for authentication.

Setup Credentials:

# Create new user and API key
just demo-user

# Create with specific details
just demo-user --name "Your Name" --email your@email.com

# Force create new credentials
just demo-user --force

Credentials Location: .local/config.json

Shared Across Demos: All demos use the same credentials file, so you only need to run this once.

Demo Flags

Most demos accept comma-separated flags to control behavior. Default behavior reuses existing credentials and graph.

Available Flags:

  • new-user - Create a new user (implies new-graph)
  • new-graph - Create a new graph
  • skip-queries - Skip verification queries after ingestion

Examples:

# Default: reuse existing user and graph, regenerate data
just demo-custom-graph

# Create new graph for existing user
just demo-custom-graph new-graph

# Create new user and graph
just demo-custom-graph new-user,new-graph

# Skip queries
just demo-custom-graph skip-queries

Running Individual Steps

Each demo has a main.py that runs all steps automatically. For manual control, you can run individual numbered scripts:

Custom Graph Demo:

cd examples/custom_graph_demo
uv run 01_setup_credentials.py
uv run 02_create_graph.py
uv run 03_generate_data.py
uv run 04_upload_ingest.py
uv run 05_query_graph.py --all

Note: The just commands are the recommended way to run demos as they handle all setup automatically.

Data Ingestion Pipeline

All demos follow the same data ingestion pattern:

  1. Generate Parquet Files - Create node and relationship data
  2. Upload to S3 - Get presigned URLs and upload files
  3. Create Staging Tables - Load Parquet files into DuckDB staging
  4. Validate Data - Query staging tables with SQL
  5. Ingest to Graph - Load from DuckDB into graph database

This pipeline demonstrates the production data loading workflow used by RoboSystems.

Understanding the Output

Successful Demo Output:

✓ User authenticated
✓ Graph created: kg1a2b3c4d5e
✓ Data generated: 6 files
✓ Files uploaded to S3
✓ Staging tables created
✓ Data ingested to graph
✓ Queries executed successfully

Example Query Results:
- Trial Balance: 20 accounts
- Income Statement: Net Income $42,000
- Balance Sheet: Total Assets $125,000

Common Issues:

  • "User already exists" - Default behavior reuses existing user, or use new-user flag
  • "Graph already exists" - Default behavior reuses existing graph, or use new-graph flag
  • "API connection failed" - Ensure RoboSystems is running (just start)
  • "Permission denied" - Check credentials in config.json

Next Steps

After running the demos:

  1. Explore the Data:

    • Use the query examples as templates
    • Modify queries to explore different patterns
    • Try the Graph API directly via just graph-query

  2. Integrate with Applications:

  3. Build Your Own:

    • Use custom_graph_demo as a template
    • Define your own schema in JSON
    • Generate data specific to your domain
    • Load and query via the same pipeline

Related Documentation

Support

For issues or questions: