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 built with embeddings, semantic enrichment, and confidence scoring for LLM-powered 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
- LadybugDB Graph Database: Purpose-built embedded graph database with columnar storage optimized for financial analytics
- Dedicated Infrastructure: Tiered graph infrastructure with dedicated instances and configurable memory allocation
- Subgraphs (Workspaces): AI memory graphs, data workspaces with fork & publish, and isolated environments for development and team collaboration
- 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
# Install uv and just
brew install uv just
# Start robosystems backend api
just start
# Start robosystems with frontend apps (robosystems-app, roboledger-app, roboinvestor-app)
just start allThis 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
Service URLs:
| Service | URL |
|---|---|
| Main API | http://localhost:8000 |
| Graph API | http://localhost:8001 |
| Dagster UI | http://localhost:8002 |
With just start all (frontend apps):
| App | URL |
|---|---|
| RoboSystems App | http://localhost:3000 |
| RoboLedger App | http://localhost:3001 |
| RoboInvestor App | http://localhost:3002 |
# Setup Python environment (uv automatically handles Python versions)
just initSee 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.
just test-all # Tests with code quality
just test # Default test suite
just test adapters # Test specific module
just test-cov # Tests with coveragejust logs api # View API logs (last 100 lines)
just logs api lines=200 # View more lines
just logs api follow=1 # Tail API logs
just logs-grep api "pipeline" 500 # Search API logsSee justfile for 50+ development commands including database migrations, CloudFormation linting, graph operations, administration, and more.
- Docker & Docker Compose
- 8GB RAM minimum
- 20GB free disk space
uvfor Python package and version managementjustfor project command runner
- Fork this repo
- AWS account with IAM Identity Center (SSO)
- Run
just bootstrapto configure OIDC and GitHub variables
See the Bootstrap Guide for complete instructions.
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: (configuration)
- Embedded columnar graph database purpose-built for financial analytics
- Native DuckDB integration for high-performance staging and ingestion
- Tiered infrastructure with configurable memory, rate limits, and subgraph allocations
- Shared tier hosts public repositories (SEC, industry, economic) with read replicas
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.
A curated knowledge graph of US public company financial data from SEC EDGAR XBRL filings. Runs on the shared LadybugDB tier, accessible via MCP tools, Cypher queries, and the AI agent.
Pipeline: EDGAR → Download → Process (Parquet) → Enrich (fastembed) → Stage (DuckDB) → Materialize (LadybugDB)
Graph: 14 node types (Entity, Report, Fact, Element, Structure, Association, FactSet, Classification, ...) and 24 relationship types modeling the full XBRL reporting hierarchy — from company filings down to individual financial facts with their taxonomy relationships and disclosure classifications.
Enrichment: Every element is mapped to ~50 canonical financial concepts (revenue, net_income, total_assets, etc.) via fastembed cosine similarity. Structures are classified by statement type. Associations are tagged with disclosure types from the Seattle Method disclosure-mechanics taxonomy. Offline knowledge artifacts (PageRank, BFS classification, cross-filing consensus) refine confidence scores using an icebug graph built from the full corpus.
just sec-load NVDA 2025 # Load NVIDIA filings locally
just sec-health # Check SEC database healthSee SEC Adapter and SEC Pipeline for detailed documentation.
- 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, AI memory operations, workspace management, and cross-database financial analysis
- Handler Pool: Managed MCP handler instances with resource limits
- 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
- AI Operations Only: Credits are consumed exclusively by AI agent calls (Anthropic Claude via AWS Bedrock)
- Token-Based Billing: ~38 credits per agent call, billed on actual token usage
- Storage Included: All database operations, queries, imports, exports, and storage are included in tier pricing
- MCP Tool Access: Unlimited — no credits consumed for external MCP tool calls
RoboSystems provides comprehensive client libraries for building applications:
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
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
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
- 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
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
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Apache-2.0 © 2026 RFS LLC