RoboSystems LogoRoboSystems

Open Source RoboSystems

Build powerful financial analysis tools with SEC filings, graph databases, and AI integration. Deploy locally or to AWS with complete infrastructure automation.

Get Started with RoboSystems

Clone the repository and run the complete stack locally or deploy to AWS

Quick Start - Docker Development Environment

Complete stack with all services configured

The recommended way to run RoboSystems. Includes PostgreSQL with automatic migrations, graph database, Valkey message broker, and all development services pre-configured.

# Clone the repository
git clone https://github.com/RoboFinSystems/robosystems.git
cd robosystems

# Install uv and just
brew install uv just

# Start all services via Docker Compose
just start

# Services available at:
# API: http://localhost:8000
# Docs: http://localhost:8000/docs

Powerful Use Cases

From SEC financial analysis to AI-powered insights, build sophisticated financial applications with RoboSystems

SEC XBRL Pipeline

Load and query financial filings locally

Load company financial filings (10-K, 10-Q) by ticker symbol into a local graph database. Query revenue, net income, assets, and other GAAP metrics across multiple years with Cypher queries.

What You Can Do:

  • ✓Download and process SEC filings for any public company
  • ✓Query financial metrics using Cypher graph database language
  • ✓Integrate with Claude Desktop or Claude Code via MCP
  • ✓Access programmatically via Python or TypeScript clients
  • ✓Compare financials across companies and time periods

Quick Start - Load NVIDIA Filings:

# Start RoboSystems services
just start

# Create a test account with SEC access
just demo-sec

# Load NVIDIA filings (all available years)
just sec-load MSFT

# Query revenue data
just graph-query sec "MATCH (e:Entity)-[:ENTITY_HAS_REPORT]->(r:Report) RETURN r LIMIT 5"
View Full SEC Pipeline Documentation →

AI Integration via MCP

Connect Claude Desktop, Claude Code, or any MCP client

Use the Model Context Protocol (MCP) to give AI assistants direct access to your financial data. Ask questions in natural language and let Claude query your knowledge graph automatically.

Integration Options:

  • ✓Claude Desktop:Add to your config for conversational financial analysis
  • ✓Claude Code:Query financial data while coding and building applications
  • ✓Custom MCP Clients:Build your own AI-powered financial tools

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "robosystems": {
      "command": "npx",
      "args": ["-y", "@robosystems/mcp"],
      "env": {
        "ROBOSYSTEMS_API_URL": "http://localhost:8000",
        "ROBOSYSTEMS_API_KEY": "rfs_your_api_key_here",
        "ROBOSYSTEMS_GRAPH_ID": "sec"
      }
    }
  }
}

Query Your Knowledge Graph:

  • •"What was Apple's revenue for the last 5 years?"
  • •"Compare NVIDIA and AMD net income trends"
  • •"Show me Tesla's total assets by quarter"

AI Memory & Workspaces:

  • •"Create a memory workspace and save what we found about margins"
  • •"What patterns did we identify in last quarter's analysis?"
  • •"Fork the graph and build a custom element mapping"

Client Libraries & SDKs

Install RoboSystems client libraries for your preferred programming language

TypeScript / JavaScript

Official TypeScript client with React components and hooks.

npm install @robosystems/client
npm →GitHub →

Python

Python client library with Jupyter notebook support.

pip install robosystems-client
PyPI →GitHub →

MCP Client

Model Context Protocol client for AI agent integration.

npx -y @robosystems/mcp
npm →GitHub →
Fork & Deploy

Bootstrap Your Fork

Deploy your own RoboSystems instance with secure GitHub OIDC authentication. No AWS credentials stored in GitHub - just fork, bootstrap, and deploy.

Secure GitHub OIDC Federation

No AWS credentials stored anywhere

No Secrets

No long-term AWS credentials stored in GitHub

Scoped Access

Credentials scoped to specific repo/branch

Short Sessions

1-hour max session - minimal exposure window

Prerequisites

  • 1
    AWS IAM Identity Center (SSO)

    Enabled with admin permissions

  • 2
    CLI Tools

    aws CLI v2, gh CLI, jq, direnv

  • 3
    GitHub Auth

    Token with repo, admin:org, workflow scopes

Quick Install (macOS)

brew install awscli gh jq direnv

Bootstrap in 3 Commands

1Configure AWS SSO
aws configure sso --profile robosystems-sso
2Run Bootstrap
just bootstrap
3Deploy to Production
just deploy prod

What bootstrap creates: OIDC Identity Provider, IAM Roles, ECR Repository, GitHub Variables, and AWS Secrets Manager entries - all automated. Production deploys via CloudFormation templates with GitHub Actions CI/CD.

API Access Modes

Choose how your API is accessed - from private development to full production with custom domains.

internalDefault

Development Mode

Internal ALB with bastion tunnel

  • + No domain required
  • + Secure private access
  • + SSM port forwarding
public-http

Quick Public

Internet-facing ALB without TLS

  • + No domain required
  • + Fast testing access
  • - No HTTPS encryption
publicRecommended

Production

Full HTTPS with custom domain

  • + ACM certificates auto-generated
  • + Route 53 DNS auto-configured
  • + OAuth integrations work
Full Bootstrap Guide in Wiki

Ready to Create Your Own Financial Knowledge Graph?

Get started building your own financial knowledge graph today with our open source platform - on your laptop or in the cloud.

Fork on GitHubWiki