RECAPAI

Backend service built with FastAPI, Socket.IO, MongoDB, Redis, LangChain, and LangGraph.

This repository is the API and realtime backend for a multi-tenant AI application. It combines classic business endpoints with AI-powered workflows such as chat, lead-agent orchestration, stock-agent orchestration, stock data and research, meeting transcription, voice cloning, TTS, image generation, and Google Sheets sync.

What the service does

• JWT authentication with bootstrap flow for the first super admin
• Multi-organization access control using X-Organization-ID
• AI chat conversations with background response processing
• Lead-agent conversations with runtime selection, skills, tools, and plan retrieval
• Stock-agent conversations with isolated LangGraph state, runtime selection, user-managed skills, planning snapshots, and specialist subagent delegation
• Stock catalog, company data, financial reports, price history, intraday data, watchlists, research reports, schedules, and backtests
• Google Sheets connection management and async sheet sync
• Meeting management plus realtime speech-to-text and note generation
• Voice cloning and text-to-speech generation
• Image upload and async image generation
• Analytics endpoints built on synchronized sheet data

Architecture at a glance

• REST API: FastAPI routers mounted under /api/v1
• Realtime transport: Socket.IO mounted on the same ASGI app
• Persistence: MongoDB for application data and LangGraph checkpointing
• Queue and fan-out: Redis for queues and optional Socket.IO scaling
• AI orchestration: LangChain and LangGraph, with separate lead-agent and stock-agent runtimes/checkpoint collections
• External providers:
  • OpenAI and Azure OpenAI for LLM access
  • Deepgram for speech-to-text
  • MiniMax for voice and audio generation
  • Cloudinary for media storage
  • Google Sheets service account for sheet sync
  • vnstock for Vietnam stock market data
  • DDGS MCP server for normalized web research tools used by research-oriented stock workflows

Runtime requirements

The current settings model requires these services or credentials at startup:

• MongoDB
• Redis
• JWT secret and internal API key
• Google service account credentials
• Cloudinary credentials
• Deepgram API key
• MiniMax API key
• vnstock API key

Some AI endpoints also need LLM configuration such as OPENAI_API_KEY or Azure OpenAI settings.

Source of truth for required environment variables is app/config/settings.py.

Quick start

1. Create a virtual environment

python -m venv .venv

Activate it in your shell, then install dependencies:

pip install -r requirements.txt

2. Configure environment variables

Start from .env.example:

Copy-Item .env.example .env

or on Unix-like shells:

cp .env.example .env

Then fill in the required values. The app currently expects, at minimum:

JWT_SECRET_KEY=
INTERNAL_API_KEY=
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=ai_service
REDIS_URL=redis://localhost:6379

GOOGLE_SERVICE_ACCOUNT_JSON=
GOOGLE_SERVICE_ACCOUNT_EMAIL=

OPENAI_API_KEY=
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_API_VERSION=
AZURE_OPENAI_LEGACY_CHAT_DEPLOYMENT=

MINIMAX_API_KEY=
DEEPGRAM_API_KEY=

CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

VNSTOCK_API_KEY=

Notes:

• .env.example is only a starting point. app/config/settings.py is the authoritative reference.
• REDIS_URL is used by the API process and background workers.
• If you only configure one LLM provider, configure the routes and features that depend on that provider accordingly.

3. Start infrastructure

You need MongoDB and Redis running before starting the API.

Example local defaults used by the app:

• MongoDB: mongodb://localhost:27017
• Redis: redis://localhost:6379

4. Run the API

uvicorn app.main:combined_app --reload --port 8080

Important details:

• REST API base path: http://localhost:8080/api/v1
• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• Socket.IO is mounted on the same server root

5. Run background workers

Some features rely on Redis-backed workers.

Image generation worker:

python -m app.workers.image_generation_worker

Meeting note worker:

python -m app.workers.meeting_note_worker

Sheet sync worker:

python -m app.workers.sheet_sync_worker

Stock research worker:

python -m app.workers.stock_research_worker

6. Run tests

pytest

MCP web search setup

The application uses MCP for normalized web research tools. The default provider is the official DDGS MCP server launched from the app environment via:

ddgs mcp

Install the dependency into the same Python environment as the app:

pip install "ddgs[mcp]"

Notes:

• requirements.txt already includes ddgs[mcp]
• DDGS supports proxy configuration via the inherited DDGS_PROXY environment variable
• Direct invocations can also pass an explicit proxy argument, for example:

ddgs mcp -pr socks5h://127.0.0.1:9150

• The application-level research contract remains search and fetch_content, while the underlying MCP provider can change later if tool normalization is preserved
• Stock research and the stock-agent event_analyst depend on these normalized tools for current source-backed event/news/catalyst research

API conventions

Authentication

Typical first-time bootstrap flow:

1. POST /api/v1/auth/bootstrap-super-admin
2. POST /api/v1/auth/login
3. Use the returned bearer token in Authorization: Bearer <token>

Organization scoping

Most business and AI routes require:

• Authorization: Bearer <token>
• X-Organization-ID: <organization-id>

If X-Organization-ID is missing, the API returns 400.

Internal endpoints

Routes under /api/v1/internal are intended for internal automation or scheduler use and require the X-API-Key header to match INTERNAL_API_KEY.

Stock-agent runtime

The stock-agent API is separate from the generic lead-agent API. It uses its own repositories and LangGraph checkpoint collections so stock-agent conversations, messages, skills, skill access, and runtime thread state do not share lead-agent storage.

Stock-agent turns support:

• Runtime catalog selection through /api/v1/stock-agent/catalog
• User-selectable tool discovery through /api/v1/stock-agent/tools
• Caller-owned stock-agent skill CRUD and per-organization enablement
• Async message submission through /api/v1/stock-agent/messages
• Conversation history and latest plan snapshot retrieval

The parent stock agent can delegate synthesis-ready subtasks through validated subagent IDs:

• general_worker: generic isolated stock-agent worker for delegated work that has no specialist runtime
• event_analyst: specialist for Vietnam-listed equity events, news, catalysts, policy/regulatory developments, macro developments, and industry developments; uses only normalized MCP search and fetch_content
• technical_analyst: specialist for daily (1D) technical reads and technical trading-plan evidence; uses deterministic tools for indicator computation, optional OHLCV inspection, and supported backtest templates

Specialist subagents return evidence packages to the parent stock agent. They do not own the final user-facing all-factor recommendation.

Main route groups

Route group	Purpose
/api/v1/health	Basic health check
/api/v1/auth	Login, password change, bootstrap super admin
/api/v1/users	User management and current-user queries
/api/v1/organizations	Organization CRUD and membership management
/api/v1/chat	AI conversation messaging and history
/api/v1/lead-agent	Lead-agent messaging, plan retrieval, skills, tools, runtime catalog
/api/v1/stock-agent	Stock-agent messaging, plan retrieval, skills, tools, runtime catalog
/api/v1/sheet-connections	Google Sheets connection CRUD, preview, data access, sync status
/api/v1/stocks	Stock catalog, company tabs, financial reports, prices, intraday data
/api/v1/stocks/watchlists	Watchlist CRUD and watchlist items
/api/v1/stock-research/reports	Async stock research report catalog, creation, detail, and history
/api/v1/stock-research/schedules	Recurring stock research schedule CRUD and manual run trigger
/api/v1/backtests	Backtest templates and execution
/api/v1/analytics	Analytics endpoints over synchronized data
/api/v1/images	Image upload and asset management
/api/v1/image-generations	Async image generation jobs
/api/v1/voices	Voice clone, voice list, preview, delete
/api/v1/tts	Generate audio, stream audio, list audio assets
/api/v1/meetings	Meeting listing, metadata updates, utterances, note chunks
/api/v1/internal	Internal triggers such as sync kickoff and stock research dispatch

Realtime behavior

The ASGI entrypoint is app.main:combined_app, which combines FastAPI and Socket.IO.

Socket.IO is used for:

• Streaming chat, lead-agent, and stock-agent responses back to the client
• Live speech-to-text sessions
• Meeting recording and note-generation workflows
• Realtime TTS streaming

Connection auth uses the same JWT token model as the REST API.

Project structure

ai_service_kiro/
|-- app/
|   |-- main.py                 # FastAPI + Socket.IO entrypoint
|   |-- api/                    # REST routers and dependencies
|   |-- agents/                 # AI agents, including lead-agent and stock-agent runtimes
|   |-- services/               # Application and domain services
|   |-- infrastructure/         # External providers and integrations
|   |-- repo/                   # Data-access repositories
|   |-- domain/                 # Models and API schemas
|   |-- socket_gateway/         # Socket.IO auth, server, and gateway logic
|   |-- workers/                # Background worker entrypoints
|   `-- config/                 # Settings, logging, MCP config
|-- doc/                        # Frontend integration guides and feature docs
|-- scripts/                    # Helper scripts and local run helpers
|-- tests/                      # Unit and integration tests
|-- requirements.txt
`-- README.md

Feature-specific docs

The doc/feature directory contains integration notes for consumers of this backend. Useful starting points:

• Backtest frontend guide
• Meeting frontend guide
• Meeting management guide
• Live STT frontend guide
• Stocks frontend guide
• Stock company guide
• Stock financial report guide
• Stock price guide
• Stock research frontend guide
• Stock research runtime metadata guide
• Stock watchlist guide
• Lead-agent skill guide
• Lead-agent catalog guide
• Lead-agent subagent guide

Notes for contributors

• The current repository has both REST and realtime concerns in the same service. Changes often need to consider both API and Socket.IO flows.
• A large portion of the business logic is organization-scoped. Check auth and membership requirements before adding new endpoints.
• If you add or change environment variables, update both app/config/settings.py and .env.example.