RoboSystems

RoboSystems is an enterprise-grade financial knowledge graph platform that transforms complex financial and operational data into actionable intelligence through graph-based analytics and AI-powered insights.

• Graph-Based Financial Intelligence: Leverages graph database technology to model complex financial relationships
• AI-Native Architecture: Context graphs for LLM-powered financial and operational AI driven analytics
• Model Context Protocol (MCP): Standardized server and client for LLM integration
• Multi-Source Data Integration: SEC XBRL filings, QuickBooks accounting data, and custom financial datasets
• Enterprise-Ready Infrastructure: Multi-tenant architecture with tiered scaling and production-grade query management
• Developer-First API: RESTful API designed for integration with financial applications

Core Features

• LadybugDB Graph Database: Purpose-built embedded graph database with columnar storage optimized for financial analytics
• Multi-Tenant Architecture: Multiple isolated graph databases per customer with tiered scaling and memory allocations
• Subgraphs (Workspaces): Create isolated environments for development, testing, and team collaboration within a parent graph
• AI Agent Interface: Natural language financial analysis with text-to-Cypher via Model Context Protocol (MCP)
• Entity & Generic Graphs: Curated schemas for RoboLedger/RoboInvestor, plus custom schema support
• Shared Repositories: SEC XBRL filings knowledge graph for context mining and benchmarking
• QuickBooks Integration: Complete accounting synchronization with trial balance creation
• DuckDB Staging System: High-performance data validation and bulk ingestion pipeline
• Dagster Orchestration: Data pipeline orchestration for SEC filings, backups, billing, and scheduled jobs
• Credit-Based Billing: Flexible credits for AI operations based on token usage or storage overage

Quick Start

Docker Development Environment

# Install uv (Python package and version manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or on macOS with Homebrew: brew install uv

# Install just (command runner)
uv tool install rust-just
uv tool update-shell  # Adds ~/.local/bin to PATH (restart terminal after)

# Start all services (includes automatic migrations and seeds)
just start

This initializes the .env file and starts the complete RoboSystems stack with:

• Graph API with LadybugDB and DuckDB backends
• Dagster for data pipeline orchestration
• PostgreSQL for graph metadata, IAM and Dagster
• Valkey for caching, SSE messaging, and rate limiting
• Localstack for S3 and DynamoDB emulation

Local Development

# Setup Python environment (uv automatically handles Python versions)
just init

Examples & Demos

See RoboSystems in action with runnable demos that create graphs, load data, and execute queries with the robosystems-client:

just demo-sec               # Loads NVIDIA's SEC XBRL data via Dagster pipeline
just demo-accounting        # Creates chart of accounts with 6 months of transactions
just demo-custom-graph      # Builds custom graph schema with relationship networks

• SEC Demo - Real public company financials from SEC XBRL filings
• Accounting Demo - Double-entry bookkeeping with trial balance and financial statements
• Custom Graph Demo - Generic graph with custom schema and relationship patterns

Each demo has a corresponding Wiki article with detailed guides.

Development Commands

Testing

just test-all               # Tests with code quality
just test                   # Default test suite
just test adapters          # Test specific module
just test-cov               # Tests with coverage

Log Monitoring

just logs api 200                    # View API logs
just logs dagster-webserver 200      # View Dagster logs
just logs-grep api "pipeline" 500    # Search API logs
just logs-follow dagster-webserver   # Tail Dagster logs

See justfile for 50+ development commands including database migrations, CloudFormation linting, graph operations, administration, and more.

Prerequisites

System Requirements

• Docker & Docker Compose
• 8GB RAM minimum
• 20GB free disk space

Required Tools

• uv for Python package and version management
• rust-just for project command runner (installed via uv)

Deployment Requirements

• Fork this repo
• AWS account with IAM Identity Center (SSO)
• Run just bootstrap to configure OIDC and GitHub variables

See the Bootstrap Guide for complete instructions.

Architecture

RoboSystems is built on a modern, scalable architecture with:

Application Layer:

• FastAPI REST API with versioned endpoints (/v1/)
• MCP Server for AI-powered graph database access
• Agent Interface for text-to-Cypher natural language queries
• Dagster for data pipeline orchestration and background jobs

LadybugDB Graph Database:

• Embedded columnar graph database purpose-built for financial analytics
• Native DuckDB integration for high-performance staging and ingestion
• Multi-tenant isolation with dedicated databases per entity
• Subgraph support for development workspaces and team collaboration
• Tiered infrastructure: Standard (multi-tenant), Large (dedicated r7g.large, 10 subgraphs), XLarge (dedicated r7g.xlarge, 25 subgraphs)

Data Layer:

• PostgreSQL for IAM, graph metadata, and Dagster
• Valkey for caching, SSE messaging, and rate limiting
• AWS S3 for data lake storage and static assets
• DynamoDB for instance/graph/volume registry

Infrastructure:

• ECS Fargate for API, Workers, and Dagster (ARM64/Graviton with Spot capacity)
• EC2 auto-scaling groups for LadybugDB writer clusters
• RDS PostgreSQL + ElastiCache Valkey
• CloudFormation infrastructure deployed via GitHub Actions (OIDC)

For detailed architecture documentation, see the Architecture Overview in the Wiki.

AI

Model Context Protocol (MCP)

• Financial Analysis: Natural language queries across entity and benchmark data
• Cross-Database Queries: Compare entity data against SEC public data
• Tools: Rich toolkit for graph queries, schema introspection, fact discovery, and cross-database financial analysis
• Handler Pool: Managed MCP handler instances with resource limits

Agent System

• Multi-agent architecture with intelligent routing
• Dynamic agent selection based on query context
• Parallel query processing with context-aware responses
• Extensible framework for custom domain expertise

Credit System

• Credit Value Anchor: 1 credit = 1 GB/day of storage
• Flexible Usage: Use credits for AI operations OR storage overage—your choice
• AI Operations: Token-based billing for Anthropic Claude API calls via AWS Bedrock
• Storage Overage: Additional storage beyond tier allocation billed at 1 credit/GB/day
• Sustainable Operations: Credit-based model enables transparent cost tracking and predictable billing aligned with actual usage

Client Libraries

RoboSystems provides comprehensive client libraries for building applications:

MCP (Model Context Protocol) Client

AI integration client for connecting Claude and other LLMs to RoboSystems.

npx -y @robosystems/mcp

• Features: Claude Desktop integration, natural language queries, graph traversal, financial analysis
• Use Cases: AI agents, chatbots, intelligent assistants, automated research
• Documentation: npm | GitHub

TypeScript/JavaScript Client

Full-featured SDK for web and Node.js applications with TypeScript support.

npm install @robosystems/client

• Features: Type-safe API calls, automatic retry logic, connection pooling, streaming support
• Use Cases: Web applications, Node.js backends, React/Vue/Angular frontends
• Documentation: npm | GitHub

Python Client

Native Python SDK for backend services and data science workflows.

pip install robosystems-client

• Features: Async/await support, pandas integration, Jupyter compatibility, batch operations
• Use Cases: Data pipelines, ML workflows, backend services, analytics
• Documentation: PyPI | GitHub

Documentation

User Guides (Wiki)

• Getting Started - Quick start and overview
• Bootstrap Guide - Fork and deploy to your AWS account
• Architecture Overview - System design and components
• SEC XBRL Pipeline - Working with SEC financial data
• Accounting Demo - Complete guide to graph-based accounting workflows

Developer Documentation (Codebase)

Core Services:

• Operations - Business workflow orchestration
• Adapters - External service integrations (SEC, QuickBooks)
• Schemas - Graph schema definitions
• IAM Models - Database models and migrations
• API Models - API request/response models
• Configuration - Configuration management
• Dagster - Data pipeline and task orchestration

Graph Database System:

• Graph API - Graph API overview
• Backends - Backend abstraction layer
• Client Factory - Client factory system
• Core Services - Core services layer

Middleware Components:

• Authentication - Authentication and authorization
• Graph Routing - Graph routing layer
• MCP - MCP tools and pooling
• Billing - Subscription and billing management
• Observability - OpenTelemetry observability
• Robustness - Circuit breakers and retry policies

Infrastructure:

• CloudFormation - AWS infrastructure templates
• Setup Scripts - Bootstrap and configuration scripts

Development Resources:

• Examples - Runnable demos and integration examples
• Tests - Testing strategy and organization
• Admin Tools - Administrative utilities and cli

Security & Compliance:

• SECURITY.md - Security features
• COMPLIANCE.md - SOC 2 compliance

API Reference

• API reference
• API documentation
• OpenAPI specification

Support

• Issues
• Wiki
• Projects
• Discussions

License

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

Apache-2.0 © 2026 RFS LLC