RoboSystems is a financial intelligence platform that connects disparate data sources, builds domain ontologies as knowledge graphs, and provides AI-powered tools for accounting, financial reporting, investment management, and analysis. It powers RoboLedger and RoboInvestor. - LadybugDB Graph Database: Embedded columnar graph database with native DuckDB staging, LanceDB vector search, and tiered i
Add this skill
npx mdskills install RoboFinSystems/robosystemsComprehensive financial intelligence platform with graph database, AI agents, and multi-source integration
1# RoboSystems23RoboSystems is a financial intelligence platform that connects disparate data sources, builds domain ontologies as knowledge graphs, and provides AI-powered tools for accounting, financial reporting, investment management, and analysis. It powers [RoboLedger](https://roboledger.ai) and [RoboInvestor](https://roboinvestor.ai).45- **LadybugDB Graph Database**: Embedded columnar graph database with native DuckDB staging, LanceDB vector search, and tiered infrastructure6- **Extensions**: Domain schemas that drive OLTP tables, API routes, data pipelines, and dedicated frontend apps. Extensions share a single database with schema-per-tenant isolation and materialize to the graph7- **Document Search**: Full-text and semantic search across SEC filings, uploaded documents, and connected sources via OpenSearch8- **AI-Native Architecture**: Context graphs with embeddings, semantic enrichment, and confidence scoring for LLM-powered analytics9- **Model Context Protocol (MCP)**: Standardized server and [client](https://www.npmjs.com/package/@robosystems/mcp) for LLM integration with schema-aware tools10- **Multi-Source Data Integration**: SEC XBRL filings, QuickBooks accounting data via dbt pipelines, and custom financial datasets11- **Enterprise-Ready Infrastructure**: Multi-tenant architecture with tiered scaling and production-grade query management12- **Developer-First API**: RESTful API designed for integration with financial applications1314## Platform1516The platform provides the core infrastructure that all extensions build on:1718- **Dedicated Infrastructure**: Tiered graph infrastructure with dedicated instances and configurable memory allocation1920- **AI Agent System**: Autonomous financial operations — graph queries, taxonomy mapping, report generation — with automatic credit tracking and SSE progress streaming21- **Shared Repositories**: SEC XBRL filings knowledge graph for context mining and benchmarking22- **Document Management**: Upload, index, and search documents with full-text and semantic search via OpenSearch23- **DuckDB Staging System**: High-performance data validation and bulk ingestion pipeline24- **Dagster Orchestration**: Data pipeline orchestration for SEC filings, QuickBooks sync, backups, billing, and scheduled jobs25- **Credit-Based Billing**: Flexible credits for AI operations based on token usage26- **Subgraphs (Workspaces)**: AI memory graphs, data workspaces with fork & publish, and isolated environments for development and team collaboration2728## Extensions2930Each extension defines a domain schema and provides OLTP tables, API routes, data pipelines, and a dedicated frontend app. All extensions share a single PostgreSQL database with schema-per-tenant isolation and materialize to the graph. See [Schema Extensions](/robosystems/schemas/README.md) for details.3132### [RoboLedger](https://roboledger.ai)3334Accounting and financial reporting extension. OLTP general ledger with schema-per-tenant PostgreSQL (accounts, transactions, journal entries, line items, dimensions), QuickBooks ELT pipeline via dbt/Dagster, SEC XBRL financial reporting, and chart of accounts.3536### [RoboInvestor](https://roboinvestor.ai)3738Portfolio management and investment tracking extension with securities, positions, trades, benchmarks, market data, and risk. Dedicated frontend app. OLTP database and API routes planned.3940## Quick Start4142### Docker Development Environment4344```bash45# Install uv and just46brew install uv just4748# Start robosystems backend api49just start5051# Start frontend apps - robosystems-app, roboledger-app, roboinvestor-app52just start apps53```5455This initializes the `.env` file and starts the complete RoboSystems stack with:5657- Graph API with LadybugDB and DuckDB backends58- Dagster for data pipeline orchestration59- PostgreSQL for graph metadata, IAM and Dagster60- Valkey for caching, SSE messaging, and rate limiting61- OpenSearch for full-text and semantic document search62- Localstack for S3 and DynamoDB emulation6364**Service URLs:**6566| Service | URL |67| ---------- | --------------------- |68| Main API | http://localhost:8000 |69| Graph API | http://localhost:8001 |70| Dagster UI | http://localhost:8002 |7172With `just start apps` (frontend apps):7374| App | URL |75| ---------------- | --------------------- |76| RoboSystems App | http://localhost:3000 |77| RoboLedger App | http://localhost:3001 |78| RoboInvestor App | http://localhost:3002 |7980### Local Development8182```bash83# Setup Python environment (uv automatically handles Python versions)84just init85```8687## Examples8889See RoboSystems in action with runnable demos that create graphs, load data, and execute queries with the `robosystems-client`:9091```bash92just demo-sec # Loads NVIDIA's SEC XBRL data via Dagster pipeline93just demo-custom-graph # Builds custom graph schema with relationship networks94```9596Each demo has a corresponding [Wiki article](https://github.com/RoboFinSystems/robosystems/wiki) with detailed guides.9798## Development Commands99100### Testing101102```bash103just test-all # Tests with code quality104just test # Default test suite105just test adapters # Test specific module106just test-cov # Tests with coverage107```108109### Log Monitoring110111```bash112just logs api # View API logs (last 100 lines)113just logs graph-api # View Graph API logs (last 100 lines)114just logs dagster-webserver # View Dagster Webserver logs115just logs dagster-daemon # View Dagster Daemon logs116```117118**See [justfile](justfile) for 50+ development commands** including database migrations, CloudFormation linting, graph operations, administration, and more.119120### Prerequisites121122#### System Requirements123124- Docker & Docker Compose125- 8GB RAM minimum126- 20GB free disk space127128#### Required Tools129130- `uv` for Python package and version management131- `just` for project command runner132133#### Deployment Requirements134135- Fork this repo136- AWS account with IAM Identity Center (SSO)137- Run `just bootstrap` to configure OIDC and GitHub variables138139See the **[Bootstrap Guide](https://github.com/RoboFinSystems/robosystems/wiki/Bootstrap-Guide)** for complete instructions.140141## Architecture142143RoboSystems is built on a modern, scalable architecture with:144145**Application Layer:**146147- FastAPI REST API with versioned endpoints148- Extension API routes feature-flagged per module149- MCP Server for AI-powered graph database access with schema-aware tools150- AI Agent System for autonomous financial operations with automatic credit tracking151- Dagster for data pipeline orchestration and background jobs152153**LadybugDB Graph Database:** ([configuration](/.github/configs/graph.yml))154155- Embedded columnar graph database purpose-built for financial analytics156- Base + extension schema architecture — extensions define domain models157- Native DuckDB integration for high-performance staging and ingestion158- LanceDB vector search for semantic element resolution (IVF-PQ indexes, 384-dim embeddings)159- Tiered infrastructure with configurable memory, rate limits, and subgraph allocations160- Shared tier hosts public repositories with read replicas161162**Data Layer:**163164- PostgreSQL for IAM, graph metadata, Dagster, and extension OLTP databases (schema-per-tenant)165- OpenSearch for full-text and semantic document search (BM25 + KNN)166- Valkey for caching, SSE messaging, and rate limiting167- AWS S3 for data lake storage and static assets168- DynamoDB for instance/graph/volume registry169170**Infrastructure:**171172- ECS Fargate for API and Dagster173- EC2 ASG for LadybugDB writer clusters174- EC2 ALB + ASG for LadybugDB shared replica clusters175- RDS PostgreSQL + ElastiCache Valkey176- OpenSearch for full-text and semantic document search177- CloudFormation infrastructure deployed via GitHub Actions with OIDC178179**For detailed architecture documentation, see the [Architecture Overview](https://github.com/RoboFinSystems/robosystems/wiki/Architecture-Overview) in the Wiki.**180181## SEC Shared Repository182183A 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.184185- **Pipeline**: EDGAR → Download → Process (Parquet) → Stage (DuckDB) → Enrich (fastembed) → Materialize (LadybugDB) → Index + Embed (OpenSearch)186- **Graph**: 14 node types and 24 relationship types modeling the full XBRL reporting hierarchy187- **Search**: Hybrid BM25 + KNN vector search across XBRL text blocks, narrative sections, and iXBRL disclosures188- **Enrichment**: Semantic element mapping, statement classification, and disclosure tagging via the [Seattle Method](http://xbrlsite.com/seattlemethod/SeattleMethod.pdf) taxonomy189190```bash191just sec-load NVDA 2025 # Load NVIDIA filings for 2025192just sec-health # Check SEC database health193```194195See [SEC Adapter](/robosystems/adapters/sec/README.md) and [SEC Pipeline](/robosystems/adapters/sec/pipeline/README.md) for detailed documentation.196197## AI198199### Model Context Protocol (MCP)200201- **Financial Analysis**: Natural language queries across enterprise data and public benchmark data202- **Cross-Database Queries**: Compare user graph data against SEC shared repository data203- **Tools**: Rich toolkit for graph queries, schema introspection, fact discovery, financial analysis, document search, and AI memory operations204- **Handler Pool**: Managed MCP handler instances with resource limits205206### Agent System207208- Unified architecture: stateless agents with protocol-based service injection209- Dual execution: API (sync/SSE) and background worker (Valkey queue + SSE progress)210- Automatic credit tracking per AI call — agents cannot forget billing211- Extensible: new agents implement `run(ctx)` and register with a decorator212- See [Agent README](/robosystems/operations/agents/README.md) for details213214### Credit System215216- **AI Operations Only**: Credits are consumed exclusively by AI agent calls (Anthropic Claude via AWS Bedrock)217- **Token-Based Billing**: Credits based on actual token usage and model cost218- **MCP Tool Access**: No credits consumed for MCP calls or database operations219220## Client Libraries221222RoboSystems provides comprehensive client libraries for building applications:223224### MCP (Model Context Protocol) Client225226AI integration client for connecting Claude and other LLMs to RoboSystems.227228```bash229npx -y @robosystems/mcp230```231232- **Features**: Claude Desktop integration, natural language queries, graph traversal, financial analysis233- **Use Cases**: AI agents, chatbots, intelligent assistants, automated research234- **Documentation**: [npm](https://www.npmjs.com/package/@robosystems/mcp) | [GitHub](https://github.com/RoboFinSystems/robosystems-mcp-client)235236### TypeScript/JavaScript Client237238Full-featured SDK for web and Node.js applications with TypeScript support.239240```bash241npm install @robosystems/client242```243244- **Features**: Type-safe API calls, automatic retry logic, connection pooling, streaming support245- **Use Cases**: Web applications, Node.js backends, React/Vue/Angular frontends246- **Documentation**: [npm](https://www.npmjs.com/package/@robosystems/client) | [GitHub](https://github.com/RoboFinSystems/robosystems-typescript-client)247248### Python Client249250Native Python SDK for backend services and data science workflows.251252```bash253pip install robosystems-client254```255256- **Features**: Async/await support, pandas integration, Jupyter compatibility, batch operations257- **Use Cases**: Data pipelines, ML workflows, backend services, analytics258- **Documentation**: [PyPI](https://pypi.org/project/robosystems-client/) | [GitHub](https://github.com/RoboFinSystems/robosystems-python-client)259260## Documentation261262### User Guides (Wiki)263264- **[Getting Started](https://github.com/RoboFinSystems/robosystems/wiki)** - Quick start and overview265- **[Bootstrap Guide](https://github.com/RoboFinSystems/robosystems/wiki/Bootstrap-Guide)** - Fork and deploy to your AWS account266- **[Architecture Overview](https://github.com/RoboFinSystems/robosystems/wiki/Architecture-Overview)** - System design and components267- **[Data Pipeline Guide](https://github.com/RoboFinSystems/robosystems/wiki/Pipeline-Guide)** - Dagster data orchestration and custom integrations268- **[SEC XBRL Pipeline](https://github.com/RoboFinSystems/robosystems/wiki/SEC-XBRL-Pipeline)** - Working with SEC financial data269- **[Custom Graph Demo](https://github.com/RoboFinSystems/robosystems/wiki/Custom-Graph-Schema)** - Guide for creating a custom schema graph demo270271### Developer Documentation (Codebase)272273**Core Services:**274275- **[Adapters](/robosystems/adapters/README.md)** - External service integrations276- **[Operations](/robosystems/operations/README.md)** - Business workflow orchestration277- **[Schemas](/robosystems/schemas/README.md)** - Graph schema definitions278- **[Configuration](/robosystems/config/README.md)** - Configuration management279- **[Dagster](/robosystems/dagster/README.md)** - Data pipeline and task orchestration280- **[IAM Models](/robosystems/models/iam/README.md)** - Database models and migrations281- **[API Models](/robosystems/models/api/README.md)** - API request/response models282283**Graph Database System:**284285- **[Graph API](/robosystems/graph_api/README.md)** - Graph API overview286- **[Client Factory](/robosystems/graph_api/client/README.md)** - Client factory system287- **[Core Services](/robosystems/graph_api/core/README.md)** - Core services layer288289**Middleware Components:**290291- **[Authentication](/robosystems/middleware/auth/README.md)** - Authentication and authorization292- **[Graph Routing](/robosystems/middleware/graph/README.md)** - Graph routing layer293- **[MCP](/robosystems/middleware/mcp/README.md)** - MCP tools and pooling294- **[Billing](/robosystems/middleware/billing/README.md)** - Subscription and billing management295- **[Observability](/robosystems/middleware/otel/README.md)** - OpenTelemetry observability296- **[Robustness](/robosystems/middleware/robustness/README.md)** - Circuit breakers and retry policies297298**Infrastructure:**299300- **[CloudFormation](/cloudformation/README.md)** - AWS infrastructure templates301- **[Setup Scripts](/bin/setup/README.md)** - Bootstrap and configuration scripts302303**Development Resources:**304305- **[Examples](/examples/README.md)** - Runnable demos and integration examples306- **[Tests](/tests/README.md)** - Testing strategy and organization307- **[Admin Tools](/robosystems/admin/README.md)** - Administrative utilities and cli308309**Security & Compliance:**310311- **[SECURITY.md](/SECURITY.md)** - Security features and compliance configuration312313## API Reference314315- [API reference](https://api.robosystems.ai)316- [API documentation](https://api.robosystems.ai/docs)317- [OpenAPI specification](https://api.robosystems.ai/openapi.json)318319## Support320321- [Issues](https://github.com/RoboFinSystems/robosystems/issues)322- [Wiki](https://github.com/RoboFinSystems/robosystems/wiki)323- [Projects](https://github.com/orgs/RoboFinSystems/projects)324- [Discussions](https://github.com/orgs/RoboFinSystems/discussions)325326## License327328This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.329330Apache-2.0 © 2026 RFS LLC331
Full transparency — inspect the skill content before installing.