RoboSystems

RoboSystems is an open-source, AI-native financial intelligence platform for accounting, financial reporting, and investment management. It gives AI agents and analysts a ledger-grade system of record they can both query and operate — closing the books, producing reports, and analyzing portfolios across accounting, market, and SEC data. Powers RoboLedger and RoboInvestor.

Platform

The platform provides the core infrastructure that all extensions build on:

• Dedicated Infrastructure: Tiered graph infrastructure with dedicated instances and configurable memory allocation
• AI Operator System: Autonomous financial Operators (Claude/MCP executors) with automatic credit tracking and SSE progress streaming. The API surface behind "AI agent" features in product copy.
• Shared Repositories: SEC XBRL filings knowledge graph for context mining and benchmarking
• Document Management: Upload, index, and search documents with full-text and semantic search via OpenSearch
• DuckDB Staging System: High-performance data validation and bulk ingestion pipeline
• Dagster Orchestration: Data pipeline orchestration for SEC filings, QuickBooks sync, backups, billing, and scheduled jobs
• Credit-Based Billing: Flexible credits for AI operations based on token usage
• Subgraphs (Workspaces): AI memory graphs and isolated environments for development and team collaboration

Extensions

Extensions are domain-specific subsystems that bring their own schema, OLTP tables, API routes, data pipelines, and dedicated frontend apps. They share a single PostgreSQL database with schema-per-tenant isolation and materialize to the graph for analytical queries.

The core platform API lives at /v1 — auth, orgs, billing, graph lifecycle (subgraphs, backups, materialize, tier changes), Cypher, and MCP — with reads as REST GETs. Every write, across both the core and extensions surfaces, is a named OperationEnvelope operation with Idempotency-Key support, audit logging, and SSE progress streaming via /v1/operations/{id}/stream.

The extensions API surface is graph-scoped at the URL level — graph_id is always a path parameter, never a query argument — and splits reads from writes by transport:

• Reads → POST /extensions/{graph_id}/graphql — Strawberry GraphQL, GraphiQL in dev, schema composed dynamically from enabled domains
• Writes → POST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name} — named REST commands

Behind the API is a CQRS operations kernel (reads/ + commands/ per domain) that's the single source of truth for business logic — GraphQL resolvers, REST operation routes, and MCP tools all delegate to the same functions. Per-domain feature flags (ROBOLEDGER_ENABLED, ROBOINVESTOR_ENABLED) gate both the routers and the GraphQL schema composition.

RoboLedger

Accounting and financial reporting extension. OLTP general ledger in schema-per-tenant PostgreSQL (accounts, transactions, journal entries, line items, dimensions); 30+ GraphQL read fields covering entities, accounts, trial balance, fiscal calendar, schedules, taxonomies, mappings, reports, and publish lists; 30+ named command operations spanning close lifecycle, schedule and closing-entry authoring, CoA→GAAP mapping associations, multi-period report authoring, and publish lists; analytical view operations over the materialized graph; QuickBooks ELT pipeline via dbt/Dagster; SEC XBRL financial reporting; AI-powered CoA→GAAP mapping via the MappingOperator. Dedicated frontend app.

RoboInvestor

Portfolio management and investment tracking extension. OLTP database with portfolios, securities, and positions in schema-per-tenant PostgreSQL; 7 GraphQL read fields (portfolios, securities, positions, holdings) and 6 named command operations for portfolio-block CRUD and security CRUD. Securities can link to entities for cross-graph research between investor portfolios and SEC public-company data via the shared repository. Dedicated frontend app.

AI

Model Context Protocol (MCP)

• Financial Analysis: Natural language queries across enterprise data and public benchmark data
• Cross-Database Queries: Compare user graph data against SEC shared repository data
• Tools: Rich toolkit for graph queries, schema introspection, fact discovery, financial analysis, document search, and AI memory operations
• Handler Pool: Managed MCP handler instances with resource limits

AI Operator System

• Unified architecture: stateless Operators (Claude/MCP executors) with protocol-based service injection
• Dual execution: API (sync/SSE) and background worker (Valkey queue + SSE progress)
• Automatic credit tracking per AI call — Operators cannot forget billing
• Extensible: add new Operators for new AI workflows; they inherit execution, credit tracking, and progress streaming automatically

Credit System

• AI Operations Only: Credits are consumed exclusively by AI Operator calls (Anthropic Claude via AWS Bedrock)
• Token-Based Billing: Credits based on actual token usage and model cost
• MCP Tool Access: No credits consumed for MCP calls or database operations

Quick Start

Docker Development Environment

# Install uv and just
brew install uv just

# Start robosystems backend api
just start

# Start frontend apps - robosystems-app, roboledger-app, roboinvestor-app
just start apps

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 IAM, graph metadata, extensions and Dagster
• Valkey for caching, SSE messaging, and rate limiting
• OpenSearch for full-text and semantic document search
• 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 apps (frontend apps):

App	URL
RoboSystems App	http://localhost:3000
RoboLedger App	http://localhost:3001
RoboInvestor App	http://localhost:3002

Local Development

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

Examples

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-roboledger        # End-to-end RoboLedger demo: bulk OLTP, schedules, FY 2025 filed report, AI close
just demo-custom-graph      # Builds custom graph schema with relationship networks

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                 # View API logs (last 100 lines)
just logs graph-api           # View Graph API logs (last 100 lines)
just logs dagster-webserver   # View Dagster Webserver logs
just logs dagster-daemon      # View Dagster Daemon logs

See justfile for 80+ 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
• just for project command runner

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

Built end-to-end on open-source engines — PostgreSQL, a columnar graph database, DuckDB, LanceDB, OpenSearch, and Valkey — assembled into a transactional core with a materialized analytical graph and integrated vector search, with no proprietary database lock-in. The components:

Application Layer:

• FastAPI REST API with versioned endpoints
• Extension GraphQL API for reads with command operations
• MCP Server for AI-powered graph database access with schema-aware tools
• AI Operator System for autonomous financial operations with automatic credit tracking
• Dagster for data pipeline orchestration and background jobs

LadybugDB Graph Database:

• Embedded columnar graph database purpose-built for financial analytics
• Base + extension schema architecture — extensions define domain models
• Native DuckDB integration for high-performance staging and ingestion
• LanceDB vector search for semantic element resolution (IVF-PQ indexes, 384-dim embeddings)
• Tiered infrastructure with configurable memory, rate limits, and subgraph allocations
• Shared tier hosts public repositories with read replicas

Data Layer:

• PostgreSQL (RDS) for IAM, graph metadata, Dagster, and extension OLTP databases (schema-per-tenant)
• OpenSearch for full-text and semantic document search (BM25 + KNN)
• Valkey (ElastiCache) for caching, SSE messaging, and rate limiting
• S3 for data lake storage and static assets
• DynamoDB for instance/graph/volume registry

Infrastructure:

• CloudFormation deployed via GitHub Actions with OIDC
• ECS Fargate for API and Dagster
• EC2 (ASG) for LadybugDB writer clusters; EC2 (ALB + ASG) for shared replica clusters

SEC Shared Repository

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 Operator.

• Pipeline: EDGAR → Download → Process (Parquet) → Stage (DuckDB) → Enrich (fastembed) → Materialize (LadybugDB) → Index + Embed (OpenSearch)
• Graph: 14 node types and 24 relationship types modeling the full XBRL reporting hierarchy
• Search: Hybrid BM25 + KNN vector search across XBRL text blocks, narrative sections, and iXBRL disclosures
• Enrichment: Semantic element mapping, statement classification, and disclosure tagging via the Seattle Method taxonomy

just sec-load NVDA 2025  # Load NVIDIA filings for 2025
just sec-health          # Check SEC database health

See SEC Adapter and SEC Pipeline for detailed documentation.

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

Documentation (Wiki)

Getting Started & Platform:

• Home / Overview · Quick Start · Core Concepts · Architecture Overview · Bootstrap Guide

Operations Layer:

• Graphs & Multi-Tenancy · Authentication & API Keys · Querying the Analytical Graph · Graph Operations · AI Operators & MCP · Shared Repositories · Credits & Billing · Pipeline Guide

Extensions Layer:

• Extensions Surface Overview · GraphQL Reads · RoboLedger Operations · RoboInvestor Operations · Connecting QuickBooks Locally

Content & Contribution Fabric:

• Information Blocks · Taxonomy & Frameworks · Event-Driven Ledger · Reporting & Rendering · Serialization & Export

Documents & Search:

• Search & AI Retrieval · Document Management · File Uploads

Demos:

• RoboLedger Demo Walkthrough · SEC XBRL Pipeline · Custom Graph Schema

Developer Documentation (Codebase)

Core Services:

• Adapters - External service integrations
• Operations - Business workflow orchestration, CQRS reads/commands kernels for extensions
• AI Operators - AI Operator framework: Claude/MCP executors, credit tracking, SSE streaming
• Schemas - Graph schema definitions
• Extensions GraphQL - Strawberry GraphQL read surface, Pydantic auto-derivation, resolver patterns
• Configuration - Configuration management
• Dagster - Data pipeline and task orchestration

Database Models:

• Platform Models - SQLAlchemy models for the platform database
• Extensions Models - SQLAlchemy models for the extensions database with schema-per-graph tenancy
• API Models - Pydantic request/response models for core platform and extensions surfaces

Graph Database System:

• Graph API - Graph API overview
• 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 and compliance configuration

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