API VEGA

RoboSystems

RoboSystems — это открытая платформа на базе искусственного интеллекта для финансового анализа, учета, финансовой отчетности и управления инвестициями. Она моделирует ваши финансовые данные как граф знаний — транзакции, факты, элементы отчетности и структуры расчётов связаны узлами и ребрами, сохраняя семантику вместо того, чтобы сводить её к строкам в таблицах. На основе этого графа система предоставляет агентам ИИ и аналитикам систему записи уровня журнала, которую можно как запросить, так и оперировать ею — закрывать книги, формировать отчёты и анализировать портфели по вашему собственномуLedger, вашим владениям и публичным filings SEC, которые доступны рядом с ними для запроса. Питает RoboLedger и RoboInvestor.

Каждый арендатор имеет свой граф. Это не подвид строк в общей таблице — это отдельная графовая БД на своём инстансе, за которой стоит выделенная OLTP-схема. Ваша онология, ваши таксономии и ваши структуры расчётов живут внутри как артефакты, которые можно читать, экспортировать и брать с собой.

Platform

Платформа обеспечивает базовую инфраструктуру, на которой строится всё остальное:

  • Выделенная инфраструктура: многоуровневая графовая инфраструктура LadybugDB с выделенными инстансами и настраиваемым объёмом памяти

  • Система AI-Операторов: автономные финансовые операторы (исполнители Claude/MCP) с автоматическим отслеживанием кредитов и SSE-потоком прогресса

  • Общие репозитории: граф знаний SEC XBRL filings для извлечения контекста и бенчмаркинга

  • Управление документами: загрузка, индексация и поиск документов с полнотекстовым и семантическим поиском через OpenSearch

  • Оплата на основе кредитов: гибкая тарификация за операции AI на основе использования токенов

  • Подграфы (Workspaces): графы памяти AI и изолированные окружения для разработки и совместной работы в команде

  • Веб-приложение: основной веб-интерфейс — управление графами, консоль запросов AI (естественный язык + Cypher по MCP), обозреватель схем, поиск документов, доступ к общим репозиториям и биллинг — robosystems-app

Основной API платформы доступен по /v1 — аутентификация, организации, биллинг, жизненный цикл графа (subgraphs, backups, materialize, tier changes), Cypher и MCP — чтение через REST GET. Любая запись — на поверхностях как для ядра, так и для расширений — это именованная операция OperationEnvelope с поддержкой Idempotency-Key, аудитом и SSE-прогрессом через /v1/operations/{id}/stream.

Extensions

Расширения — это доменно-специфические подсистемы, которые приносят свои схемы, OLTP-таблицы, API-маршруты, конвейеры данных и выделенные фронтенд-приложения. Они используют единую базу PostgreSQL с раздельной изоляцией по схеме на арендатора и материализуются в граф для аналитических запросов. Контент домена создаётся как блок-молекулы — самодостаточные конверты, объединяющие атомарные факты с их структурой, правилами и проверкой — и никогда не просто строки.

Поверхность API расширений — граф-скоуп-по URL-уровню — graph_id всегда является параметром пути, а не аргументом запроса — разделяет чтение и запись по транспорту:

  • Reads → POST /extensions/{graph_id}/graphql — Strawberry GraphQL, GraphiQL в разработке, схема формируется динамически из включённых доменов

  • Writes → POST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name} — именованные REST-команды

  • Analytical views → POST /extensions/{domain}/{graph_id}/operations/{view_name} — только для чтения аналитические операции (например, build-fact-grid, live-financial-statement), те же envelop-пакеты, что и для записей

За API стоит ядро операций CQRS (reads/ + commands/ по домену, плюс граф-backed views/) — единый источник истины для бизнес-логики: GraphQL-резолверы, REST-роуты операций и инструменты MCP делегируют вызовы в одни и те же функции. По-доменным флагам-фичам (ROBOLEDGER_ENABLED, ROBOINVESTOR_ENABLED) управляются маршрутизаторы и составление GraphQL-схемы.

RoboLedger

Расширение для учёта и финансовой отчетности — системa уровня ledger, которую ИИ и аналитики могут запросить и оперировать. В широком смысле реализует депрессив метод Seattle Method — декларативную методологию цифровой финансовой отчетности. Записи превращаются в самодостаточные молекулы: атомарные факты, связанные с их структурным аппаратом, правилами и верификацией в одном типизированном конверте, а не в простых строках. Тремя блок-молекулами задаётся основаAuthoring substrate:

  • Information Blocks — конверт для отчётного содержания: графики, отчеты, метрики и текстовые раскрытия, связанные с их набором фактов по периодам и версиям, типизированными механиками и правилами. evaluate-rules выполняет арифметические проверки (EqualTo, RollUp, RollForward, SumEquals, Exists, CoExists) по материализованным фактам; фиксация набора фактов отделяет живой закрывающий books от замороженного отчёта.

  • Event Blocks — REA-событийный учёт: вызывающие лица фиксируют произошедшее (продажа, платеж, списание актива) через структурированную лексику действий-глаголов, а реестр обработчиков выводит дебет и кредит по трёмуровню бухгалтерского баланса (Transaction → Entry → LineItem). Просмотр разрешения обработчика, выполнение для записи в главной системе (GL) атомарно, и промоция обязательств к исполнению по запросу.

  • Taxonomy Blocks — учетные рамки как данные, а не код: элементы, Association (presentation / calculation / mapping), структуры и автоматически генерируемые структурные правила в одной атомарной записи. Включают fac (фундаментальные элементы) и rs-gaap (примерно 2 000 концепций US-GAAP) за двумя уровнями публичной и арендаторской библиотеки, сопоставление CoA→GAAP зафиксировано на нижних узлах calc-DAG.

Основан на блоках:

  • Close lifecycle — финансовый календарь, подготовка закрытия, последовательность закрытия периода и повторного открытия, синхронизация с балансом, задержки QuickBooks, и незавершённые графы-обязательства; каждый блокер указывает, что мешает закрытию

  • Mapping — сопоставления CoA→GAAP и AI-поддерживаемое пакетное сопоставление через MappingOperator (уровни доверия: auto-approve / review / skip)

  • Reporting — много-периодные отчёты, формируемые из общих фактов через Reporting Style; жизненный цикл отчета (draft → under_review → filed → archived) и списки публикации для распространения

  • Forecasting — сценарии операционного плана, выстроенные по тем же структурам отчетности: правила прогноза, траектории роста по строкам и ручные утверждения по строкам, периоды прогноза возвращаются вместе с фактическими данными в чтении отчётов

  • Analytical operations — live-financial-statement формирует отчет прямо из OLTP-базы (без материализации); build-fact-grid и financial-statement-analysis запрашивают материализованный XBRL-гиперкуб графа

  • Serialization — отчёты сериализуются в веб-нативном JSON-LD (хранятся и проходят SHACL-валидирование) и в Filing-grade XBRL 2.1 (перестраиваются по требованию, валидируются в Arelle)

  • Pipelines & data — ELT QuickBooks через dbt/Dagster с настраиваемой write_policy и SEC XBRL-графическое представление

dedicated frontend app: roboledger-app.

RoboInvestor

Расширение для управления портфелем и учёта инвестиций — отслеживает владения в частных компаниях и связывает их с бизнесами, которые их выпустили.

  • Portfolio Blocks — та же молекула как и RoboLedger: портфолио и его позиции и ценные бумаги валидируются и записываются как один конверт, себестоимость и текущая стоимость хранятся в целочисленных центах и доллары, рассчитаны на границе. Позиции проходят через активный / списанный / архивный жизненный цикл; чтения возвращают portfolios, positions, holdings (сводно по эмитенту) и собранный portfolioBlock.

  • Securities — регистрируйте и поддерживайте владение инструментами (обыкновенные акции, варранты, конвертируемые ноты и т. д.) с расширяемым blob terms для деталей инструмента (страйк-цена, ликвидационная преференция, vesting)

  • Cross-graph research — безопасность может указывать на граф компании-эмитента, когда та же компания работает на платформе. Запись инвестора содержит source_graph_id эмитента как предсвязь; когда эмитент позже публикует отчёт в граф инвестора, сущность эмитента материализируется там и любые ценные бумаги, ожидающие по связке source_graph_id, находят к ней доступ. Владение затем проходит к фактам самой эмитента — Portfolio → Position → Security → Entity → Report → Fact — с доступом, ограниченным на границе совместного размещения отчета, а не на уровне OLTP.

Dedicated frontend app: roboinvestor-app.

Quick Start

Docker Development Environment

# Install uv and just
brew install uv just

# Start robosystems backend
just start

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

# Refresh images and recreate the containers that changed (after a git pull)
just upgrade

# Restart to pick up code changes; rebuild after dependency changes
just restart
just rebuild

Это инициализирует файл .env и запускает полный стек RoboSystems с:

  • Graph API с бэкендами LadybugDB и DuckDB

  • Dagster для оркестрации вычислительных конвейеров

  • PostgreSQL для IAM, метаданных графа, расширений и Dagster

  • Valkey для кэширования, SSE-уведомлений и ограничения скорости

  • OpenSearch для полнотекстового и семантического поиска документов

  • Localstack для эмуляции S3 и DynamoDB

URLs сервисов:

СервисURL
Main APIhttp://localhost:8000
Graph APIhttp://localhost:8001
Dagster UIhttp://localhost:8002

С помощью just start apps (фронтенд-приложения):

приложениеURL
RoboSystems Apphttp://localhost:3000
RoboLedger Apphttp://localhost:3001
RoboInvestor Apphttp://localhost:3002

Local Development

# Настройка окружения Python (uv автоматически подбирает версии)
just init

Examples

Посмотрите RoboSystems в действии с рабочими демо, которые создают графы, загружают данные и выполняют запросы с использованием robosystems-client:

just demo-sec               # Загружает данные SEC XBRL от NVIDIA через Dagster-пайплайн
just demo-roboledger        # Полный демо RoboLedger: массовый OLTP, графики расписаний, отчёт за FY 2025, AI-закрытие
just demo-custom-graph      # Создание пользовательской схемы графа с сетями отношений
just demo-coffee-roaster    # Сценарий синтетического производства
just demo-saas-startup      # Синтетический сценарий SaaS
just demo-roboinvestor      # Перекрёстный проход по графу от частной доли до опубликованного отчета эмитента (запустите demo-saas-startup первым)

Каждое демо имеет соответствующую статью в Wiki с подробными руководствами.

Development Commands

Testing

just test-all               # Тесты с учетом качества кода
just test                   # Стандартный набор тестов
just test adapters          # Тест специфических модулей
just test-cov               # Тесты с покрытием

Code Quality

just test-code              # Линтинг, форматирование и типизация (то, что выполняют git-хуки)
just lint fix               # Автоисправление проблем линтинга
just typecheck              # Проверка типов

Log Monitoring

just logs api                 # Просмотр логов API (последние 100 строк по умолчанию)
just logs graph-api           # Просмотр логов Graph API
just logs dagster-webserver   # Просмотр логов Dagster Webserver
just logs dagster-daemon      # Просмотр логов Dagster Daemon

См. justfile для более 100 команд разработки, включая миграции баз данных, линтинг CloudFormation, операции с графом, администрирование и многое другое.

Prerequisites

System Requirements

  • Docker & Docker Compose

  • минимум 8GB RAM

  • свободное место на диске 20GB

Required Tools

  • uv для управления пакетами и версиями Python

  • just для выполнения команд проекта

Разработано и протестировано на macOS и Linux. На Windows используйте WSL2 с клоном репозитория внутри файловой системы Linux — см. Windows Setup (WSL2) Guide.

Deployment Requirements

  • Форк этого репозитория

  • AWS-аккаунт с IAM Identity Center (SSO)

  • Запустите just bootstrap для конфигурации OIDC и переменных GitHub

См. Bootstrap Guide для полного руководства.

Architecture

Собрана from scratch на открытых движках — PostgreSQL, LadybugDB, DuckDB, LanceDB, OpenSearch и Valkey — в транзакционный ядро с материализованной аналитической графой и встроенным векторным поиском, без зависимости от проприетарной БД.

Эта открытость просачивается вверх и вниз по стосу: онтология учета, налогомы и структуры расчётов — это читаемые, переносимые артефакты, которыми вы владеете, а не конфигурации в чужой платформе — семантическое суверенное владение данными.

Multi-Tenancy & Isolation

Принцип один: каждое изоляционное пространство идентифицируется по graph_id, а не по организации — сессионный search_path, ключи кэша, idempotency-ключи, лимиты скорости и расчёт кредитов — всё пространственно в рамках графа. Два графа внутри одной организации разделяются тем же механизмом, который разделяет двух разных клиентов; внутреннего пути обхода границы не существует.

  • Один граф БД на арендатора — каждый уровень инфраструктуры имеет databases_per_instance: 1, поэтому различия между уровнями — размер инстанса, а не число арендаторов

  • Схема-per-graph OLTP — у каждого графа своя PostgreSQL-схема, search_path перезаписывается для каждого запроса, а не наследуется из пула соединений. CI-тесты закрепляют договорённость.

  • Два БД, две истории миграций — состояние платформы (идентификация, организации, биллинг) отделено от OLTP расширений; миграция в одну не касается другую.

  • Граф — производное проекцирование — OLTP-строки являются системой записи, аналитический граф восстанавливается из них blue-green, именно поэтому восстановление — это обычная процедура, а не риск.

  • Subgraphs — изолированные окружения внутри арендатора, которые разделяют кредиты и разрешения родителя — память AI, разработки, рабочие пространства команды

  • Shared repositories (SEC XBRL) — одна поверхность для чтения: читается отдельно, реплицируется отдельно, доступна рядом с вашим графом, но через него писать нельзя.

Поскольку аренда по графу обеспечивается на уровне графа, а не через предикаты приложения, один и тот же кодовый базис обслуживает управляемый SaaS, выделенную одно-арендную установку и полностью автономную самодостаточную инсталляцию без форков. Подробнее: Graphs & Multi-Tenancy.

Identity & Access

Программный доступ осуществляется через X-API-Key; веб-приложения используют короткоживущие JWT. Как именно пользователь входит в систему — решение развёртывания — пароль, WebAuthn passkey или корпоративный провайдер идентификации — публикуется по адресу GET /v1/auth/providers, чтобы одно обновление фронтенда отображало любой режим, на который настроен бэкенд.

Enterprise SSO (OIDC) и SCIM 2.0 provisioning включены в репозиторий по умолчанию — доступны даже для форков без лицензионной блокации. Provisioning — только по ссылке: SCIM создаёт учетные записи, OIDC разрешает доступ к уже созданным учетным записям, поэтому владелец идентификационного провайдера управляет жизненным циклом учётной записи в обоих направлениях.

Детали: Enterprise SSO & SCIM · Authentication & API Keys · SECURITY.md

Components

Слоёв приложения:

  • FastAPI REST API с версионируемыми конечными точками

  • Extension GraphQL read API плюс именованные REST-команды операций (CQRS)

  • MCP сервер для доступа к графовой БД на базе искусственного интеллекта — каждый граф поддерживает MCP Streamable HTTP-транспорт, аутентификацию через OAuth или API-key

  • Система AI-Operator для автономных финансовых операций с автоматическим учётом кредитов

  • Dagster для оркестрации конвейеров данных и фоновых задач

Графовая база данных LadybugDB:

  • Встроенная колоночная графовая БД, специально созданная для финансовой аналитики

  • Архитектура базовых схем и расширений — расширения определяют доменные модели

  • Нативная интеграция с DuckDB для высокой производительности на предварительной обработке и загрузке

  • LanceDB как движок семантической модальности — per-graph on-disk векторные хранилища (IVF-PQ, 384-dim embeddings) для памяти AI (remember/recall) и offload векторного поиска

  • Многоуровневая инфраструктура с настраиваемой памятью, ограничениями скорости и квотами подграфов

  • Общий уровень с публичными репозиториями — читаемые копии

Data Layer:

  • PostgreSQL (RDS) для IAM, метаданных графа, Dagster и баз OLTP расширений (схема на арендатора)

  • OpenSearch для полнотекстового и семантического поиска документов (BM25 + KNN)

  • Valkey (ElastiCache) для кэширования, SSE-уведомлений и ограничения скорости

  • S3 для хранилища данных и статических активов

  • DynamoDB для реестра инстансов/графов/томов

Infrastructure:

  • CloudFormation развёртывается через GitHub Actions с OIDC

  • ECS Fargate для API и Dagster

  • EC2 (ASG) для графских writer-узлов LadybugDB; EC2 (ALB + ASG) для общих реплик

AI

Model Context Protocol (MCP)

  • Финансовый анализ: запросы на естественном языке по корпоративным данным и публичным эталонным данным

  • Кросс-датабазевые запросы: сравнение данных вашего графа с данными SEC общего репозитория

  • Инструменты: богатый набор инструментов для графовых запросов, интроспекции схемы, обнаружения фактов, финансового анализа, поиска документов и операций AI memory

  • Handler Pool: управляемые экземпляры обработчика MCP с ограничениями ресурсов

AI Operator System

  • Единая архитектура: безсервисные Operators (исполнители Claude/MCP) с внедрением протокола

  • Двойное выполнение: API (синхронно / SSE) и фоновый воркер (очередь Valkey + прогресс SSE)

  • Автоматический учёт кредитов на каждый AI-вызов — операторы не забывают биллинг

  • Расширяемость: можно добавлять новых операторов под новые AI-воркфлоу; они наследуют выполнение, учёт кредитов и поток прогресса автоматически

Credit System

  • Только AI-операции: кредиты расходуются исключительно на вызовы AI-Operator (Anthropic Claude через AWS Bedrock)

  • Биллинг по токенам: кредиты начисляются исходя из фактического использования токенов и стоимости модели

  • Доступ к MCP-инструментам: кредиты не расходуются на MCP-вызовы или операции с базой данных

SEC Shared Repository

Куративируемый граф знаний по финансовым данным американских публичных компаний, взятый из SEC EDGAR XBRL filings. Работает на общей LadybugDB-ступени, доступен через MCP-инструменты, Cypher-запросы и AI Operator.

Полный корпус публикуется ежемесячно как один файл LadybugDB на Hugging Face — robosystems/sec-xbrl-knowledge-graphs (десятки ГБ для скачивания, более 100 ГБ на диске; карточка набора содержит точные размеры каждого снимка). just sec-dump выгружает его в data/lbug-dbs для локального Cypher, API и MCP без запуска конвейера; см. страницу вики SEC XBRL Pipeline.

  • Pipeline: EDGAR → Download → Process (Parquet) → Stage (DuckDB) → Enrich (Icebug+fastembed) → Materialize (LadybugDB) → Index + Embed (OpenSearch)

  • Graph: базовая схема плюс расширение roboledger — 20 типов узлов и 41 тип отношений, моделирующие полную иерархию XBRL-отчётности

  • Search: гибридный поиск по тексту BM25 + векторный поиск KNN по текстовым блокам XBRL, повествовательными разделами и раскрытиям iXBRL

  • Enrichment: семантическое соответствие элементов, классификация утверждений и тегирование раскрытий — применение аспектов Seattle Method к раскрытиям общего репозитория (методология, которую RoboLedger реализует шире)

См. SEC Adapter для подробной документации.

Client Libraries

RoboSystems предоставляет комплексные клиентские библиотеки для разработки приложений:

MCP (Model Context Protocol)

Каждый граф — это MCP-сервер, и URL графа является предпочтительным способом подключения — Claude, Claude Code, Cursor или любой MCP-клиент, поддерживающий HTTP-транспорт, без необходимости установки. URL выбирает граф (sec для общего SEC-репозитория, ваш graph_id для вашего графа); вход через OAuth или API-key в заголовок X-API-Key — никогда не в URL.

OAuth — вход и выбор графа. Эндпоинт без привязки к графу https://api.robosystems.ai/v1/mcp принимает OAuth: OAuth-совместимый клиент (claude.ai, Claude Code, ChatGPT, VS Code, Cursor) получает адрес авторизации, вы входите и выбираете граф, который будет покрыт подключением, и клиент держит отменяемый токен, привязанный к этому графу — не нужно вставлять ключ в текст. Для граф-уровневых URL OAuth тоже поддерживается вместе с ключом в заголовке. (Флаг развёртывания: MCP_OAUTH_ENABLED.)

claude mcp add --transport http robosystems https://api.robosystems.ai/v1/mcp

Claude Code с API key — одна команда:

"">``` claude mcp add --transport http robosystems-sec
https://api.robosystems.ai/v1/graphs/sec/mcp
--header "X-API-Key: <your key>"


**Cursor / VS Code** — добавьте в `mcp.json`:

" }
}">```
"robosystems-sec": {
  "url": "https://api.robosystems.ai/v1/graphs/sec/mcp",
  "headers": { "X-API-Key": "<your key>" }
}

Claude (claude.ai / Desktop) — Settings → Connectors → Add custom connector с URL https://api.robosystems.ai/v1/mcp (или per-graph URL): Claude обнаруживает OAuth, и вы выбираете граф на входе в систему. Страница MCP в приложении (/connect) содержит все закладки для выбранного графа и выдаёт граф-скоуп ключей для клиентов только с заголовками.

  • Документация: Wiki guide | stdio bridge (proxy-режим) для клиентов без поддержки HTTP-транспорта

TypeScript/JavaScript Client

Полнофункциональная SDK для веб- и Node.js-приложений с поддержкой TypeScript.

npm install @robosystems/client

  • Особенности: типобезопасные вызовы API, автоматическая пере попытка, пул соединений, поддержка стриминга

  • Применение: веб-приложения, бэкенд на Node.js, фронтенд на React/Vue/Angular

  • Документация: npm | GitHub

Python Client

Нативный Python SDK для бэкенд-сервисов и рабочих процессов дата-сайенс.

pip install robosystems-client

  • Особенности: поддержка async/await, интеграция с pandas, совместимость с Jupyter, пакетные операции

  • Применение: конвейеры данных, ML-работы, бэкенд-сервисы, аналитика

  • Документация: PyPI | GitHub

Documentation

Documentation (Wiki)

Getting Started & Platform:

Operations Layer:

Extensions Layer:

Content & Contribution Fabric:

Documents & Search:

Demos:

Developer Documentation (Codebase)

Каждый пакет документирует себя — читайте README в директории перед тем, как работать в ней.

Core Services:

  • Adapters - внешние сервисы и интеграции

  • Operations - оркестрация бизнес-логики, ядра чтения/запросов CQRS для расширений

  • AI Operators - фреймворк AI-Operator: исполнители Claude/MCP, учёт кредитов, SSE-потокинг

  • Schemas - определения схем графа

  • Extensions GraphQL - поверхности чтения Strawberry GraphQL, авто-генерация Pydantic, паттерны резолверов

  • Configuration - управление конфигурацией

  • Dagster - конвейеры данных и оркестрация задач

Database Models:

  • Platform Models - модели SQLAlchemy для платформенной БД

  • Extensions Models - модели SQLAlchemy для БД расширений с разделением по схемам графов

  • API Models - модели Pydantic для запросов/ответов на ядро платформы и расширения

Graph Database System:

Middleware Components:

  • Authentication - аутентификация и авторизация

  • Graph Routing - уровень маршрутизации графа

  • MCP - инструменты MCP и пуллинг

  • Billing - управление подписками и биллингом

  • Observability - наблюдаемость через OpenTelemetry

  • Robustness - защиты цепочек, политики повторной попытки

Infrastructure:

  • CloudFormation - шаблоны AWS-инфраструктуры

  • Setup Scripts - скрипты инициализации и настройки

Development Resources:

  • Examples - runnable демо и примеры интеграции

  • Tests - стратегия и структура тестирования

  • Admin Tools - административные утилиты и CLI

Security & Compliance:

  • SECURITY.md - каталог контроля безопасности с примерами реализации

  • Compliance - стеки соответствия, переключатели и SOC 2

  • Trust Center - текущая текущая ситуация по соответствию и артефакты аудита

API Reference

Support

License

Этот проект лицензирован по Apache License 2.0 — смотрите файл LICENSE для подробностей.

Apache-2.0 © 2026 RFS LLC