The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the RoboSystems listing page.
RoboSystems is an open-source, AI-native financial intelligence platform for accounting, financial reporting, and investment management. It models your financial data as a knowledge graph — transactions, facts, reporting elements, and the calculation structures that relate them are all nodes and edges, with the semantics preserved rather than flattened into rows you query around. On top of that graph 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 your own ledger, your holdings, and SEC public filings queryable alongside them. Powers RoboLedger and RoboInvestor.
Every tenant gets their own graph. Not a row-level slice of a shared table — a dedicated graph database on its own instance, with a dedicated OLTP schema behind it. Your ontology, your taxonomies, and your calculation structures live in it as artifacts you can read, export, and take with you.
The platform provides the core infrastructure that all extensions build on:
robosystems-appThe core platform API lives at /v1 — auth, orgs, billing, graph lifecycle (subgraphs, backups, materialize, tier changes), Cypher, and MCP — with reads as REST GET. 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.
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. Domain content is authored as block molecules — self-describing envelopes bundling atomic facts with their structure, rules, and verification — never bare rows.
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:
POST /extensions/{graph_id}/graphql — Strawberry GraphQL, GraphiQL in dev, schema composed dynamically from enabled domainsPOST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name} — named REST commandsPOST /extensions/{domain}/{graph_id}/operations/{view_name} — read-only analytical operations (e.g. build-fact-grid, live-financial-statement), same envelope as writesBehind the API is a CQRS operations kernel (reads/ + commands/ per domain, plus graph-backed views/) 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.
Accounting and financial reporting extension — a ledger-grade system of record that AI and analysts can both query and operate. Writes land as self-describing molecules: atomic facts bundled with their structural wiring, rules, and verification in one typed envelope, never bare rows. Three block molecules are the authoring substrate:
evaluate-rules runs arithmetic checks (EqualTo, RollUp, RollForward, SumEquals, Exists, CoExists) over materialized facts; pinning a fact set separates a live closing book from a frozen report.fac (fundamentals) and rs-gaap (~2,000 curated US-GAAP concepts) behind a two-tier public→tenant library, with CoA→GAAP mapping anchored to calc-DAG leaves.Built on the blocks:
live-financial-statement renders a statement straight from the OLTP ledger (no materialization required); build-fact-grid and financial-statement-analysis query the materialized XBRL hypercube in the graphwrite_policy, and SEC XBRL financial reportingDedicated frontend app: roboledger-app.
Portfolio management and investment tracking extension — tracks holdings in private companies and links them back to the businesses that issued them.
portfolios, positions, holdings (rolled up by issuer), and the assembled portfolioBlock.terms blob for instrument-specific detail (strike price, liquidation preference, vesting)source_graph_id up front as a pre-association; when the issuer later shares a published report into the investor's graph, the issuer's entity is materialized there and any securities waiting on that source_graph_id link to it. A holding then traverses through to the issuer's own reported facts — Portfolio → Position → Security → Entity → Report → Fact — with authorization enforced at the report-sharing boundary, not the OLTP layer.Dedicated frontend app: roboinvestor-app.
This initializes the .env file and starts the complete RoboSystems stack with:
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 |
just start runs the published images as released, so the checkout supplies configuration, not code. To run your own changes, comment out the image lines in .env: the stack is then built from the checkout, with its source mounted so an edit applies on just restart.
See RoboSystems in action with runnable demos that create graphs, load data, and execute queries with the robosystems-client:
Each demo has a corresponding documentation page with detailed guides.
See justfile for 100+ development commands including database migrations, CloudFormation linting, graph operations, administration, and more.
uv for Python package and version managementjust for project command runnerDeveloped and tested on macOS and Linux. On Windows, use WSL2 with the repo cloned inside the Linux filesystem — see the Windows Setup (WSL2) Guide.
just bootstrap to configure OIDC and GitHub variablesSee the Bootstrap Guide for complete instructions.
Built end-to-end on open-source engines — PostgreSQL, LadybugDB, 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.
That openness runs up the stack as well as down: the accounting ontology, reporting taxonomies, and calculation structures are inspectable, portable artifacts you own, not configuration trapped in a vendor platform — semantic sovereignty for your financial data.
One rule: every isolation primitive keys on graph_id, never on an organization — session search_path, cache keys, idempotency keys, rate-limit buckets, and credit accounting all namespace on the graph. Two graphs inside the same organization are separated by the identical mechanism that separates two unrelated customers; there is no "internal" path that skips the boundary.
databases_per_instance: 1, so tiers differ by instance size, not by how many tenants share one.search_path re-stamped on every request rather than inherited from a pooled connection. A CI structural test pins the contract.Because tenancy is enforced at the graph rather than in application predicates, the same codebase serves managed SaaS, a dedicated single-tenant deployment, and a fully self-hosted install with no fork. Details: Graphs & Multi-Tenancy.
Programmatic access uses X-API-Key; the browser apps use short-lived JWTs. How a person logs in is a deployment decision — password, WebAuthn passkey, or an enterprise identity provider — published at GET /v1/auth/providers, so one frontend build renders whichever posture the backend is configured for.
Enterprise SSO (OIDC) and SCIM 2.0 provisioning ship in the repository, off by default — available to any fork without a license gate. Provisioning is link-only: SCIM creates accounts and OIDC only resolves already-provisioned ones, so the identity provider owns the account lifecycle in both directions.
Details: Enterprise SSO & SCIM · Authentication & API Keys · SECURITY.md
Application Layer:
LadybugDB Graph Database:
Data Layer:
Infrastructure:
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.
The full corpus is also published monthly as one LadybugDB file on Hugging Face — robosystems/sec-xbrl-knowledge-graphs (tens of GiB to download, well over 100 GiB on disk; the dataset card carries each snapshot's exact sizes). just sec-dump pulls it into data/lbug-dbs for local Cypher, API, and MCP with no pipeline run; see the SEC XBRL Pipeline wiki page.
roboledger extension — 20 node types and 41 relationship types modeling the full XBRL reporting hierarchydisclosures and information-block tools, the holon viewer, and its own MCP serverSee SEC Adapter for detailed documentation.
RoboSystems provides comprehensive client libraries for building applications:
Every graph is an MCP server, and the graph's URL is the preferred way to connect — Claude, Claude Code, Cursor, or any MCP client that supports HTTP transports, no install required. The URL picks the graph (sec for the public SEC repository, your graph id for your own); sign in with OAuth, or put your API key in the X-API-Key header — never in the URL.
OAuth — sign in and pick a graph. The graph-agnostic endpoint https://api.robosystems.ai/v1/mcp accepts OAuth only: an OAuth-capable client (claude.ai, Claude Code, ChatGPT, VS Code, Cursor) discovers the authorization server from the endpoint, you sign in and choose the graph the connection covers, and the client holds a revocable token bound to that graph — no key to paste. Per-graph URLs accept OAuth too, alongside the key header. (Deployment flag: MCP_OAUTH_ENABLED.)
RoboLedger endpoint. https://api.robosystems.ai/v1/mcp/roboledger is the same OAuth flow for RoboLedger graphs only: sign-in offers only your RoboLedger graphs, and the connection serves the accounting tool set without workspace and platform-administration tools (subgraphs, backups, materialization, write policy). It is the endpoint for RoboLedger directory listings, which freeze one tool list per URL.
Claude Code with an API key — one command:
Cursor / VS Code — add to mcp.json:
Claude (claude.ai / Desktop) — Settings → Connectors → Add custom connector with https://api.robosystems.ai/v1/mcp (or a per-graph URL): Claude detects OAuth and you pick the graph at sign-in. The MCP page in the app (/connect) has every snippet filled in for the selected graph, and mints graph-scoped keys for header-only clients.
Full-featured SDK for web and Node.js applications with TypeScript support.
Native Python SDK for backend services and data science workflows.
Getting Started & Platform:
Operations Layer:
Extensions Layer:
Content & Contribution Fabric:
Documents & Search:
Demos:
Each package documents itself — read the README for a directory before working in it.
Core Services:
Database Models:
Graph Database System:
Middleware Components:
Infrastructure:
Development Resources:
Security & Compliance:
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Apache-2.0 © 2026 RFS LLC