How shubhamnayak1708/mars works
Project Type and Purpose
• MarS is a domain‐specific, full‐stack financial market simulation engine.
• Core functionality lives in the “mlib” library (the simulation engine), while “market_simulation” provides domain wrappers, example scripts, demos, and model serving.
• It integrates a generative foundation model (the Large Market Model) for realistic order‐level simulation and exposes both batch scripts and interactive demos (Streamlit, Ray Serve).
File Structure Analysis
Top‐level directories
• .devcontainer, .github, scripts – Dev & CI/CD setup (VS Code Dev Container, Dockerfile, GitHub Actions, pre‐commit hooks).
• mlib – Core simulation engine:
– core: Env, Engine, Exchange, States, Agents abstractions, Orderbook, Events, Transactions.
– utils: time utilities, progress-bar, tests for core functionality.
• market_simulation – Domain‐specific layer:
– conf.py: configuration of data paths and model serving.
– agents: background_agent, noise_agent, trading_agent.
– models: order_model logic, HF wrapper for uploading/downloading.
– rollout: Ray Serve server (order_model_serving), client (model_client).
– states: specific State subclasses (order_state, trans_state, trade_info_state).
– examples & demo: batch scripts (stylized facts, forecast, market impact, run_simulation) and Streamlit apps.
• download.py: one‐step data & converter download.
• scripts: install, run pre‐commit, start-order-model server.
• setup.py, pyproject.toml – packaging.
• ray_serving.yaml – Ray Serve deployment config.
README Insights
• High‐level overview: MarS engine + generative LMM + four downstream applications (stylized facts, forecasting, market impact, interactive demo).
• Technical stack: Python 3.11+, Gym‐like interface, Ray Serve for model serving, Streamlit for UI, Docker for environment.
Main Components
• Development & Deployment layer: VS Code Dev Container / Docker, GitHub Actions (CI), Ray cluster.
• Core Simulation Engine (mlib):
– Env & Engine
– Exchange & Exchange Config
– States (order_state, trans_state, trade_info_state)
– Agents (Noise, Trading, Background)
– Orderbook, Events, Transactions
• Domain Layer (market_simulation):
– Configuration (conf.py)
– Model Logic (order_model.py, HF wrapper)
– Rollout Service (Ray Serve server + ModelClient)
– Example Scripts & Streamlit Demos
• External Services & Data:
– OneDrive data store for converters & stylized facts data
– Hugging Face model repository (private)
– Ray Serve (distributed inference)
Relationships & Data Flows
• Agent → Action → Engine.process_event() → Exchange updates → State.on_open/on_trading/on_close → Agents consume new State → loop.
• Example scripts instantiate Env, register Agents and States, push Exchange events (market open/close), then iterate simulation.
• OrderModel is exposed via Ray Serve:
• order_model_serving launches a Ray Serve endpoint.
• ModelClient in rollout and examples sends requests (Prediction) → Ray Serve → LMM model → returns tokenized orders.
Architectural Patterns & Design Principles
• Layered Architecture: separation between core engine (mlib), domain wrappers (market_simulation), and presentation (demos/UI).
• Publish–Subscribe: State updates trigger Agents; zero‐copy state sharing.
• Client–Server: Model serving via Ray Serve; ModelClient abstracts RPC.
• Modular & Pluggable: custom Agents, States, Exchange configurations.
• Infrastructure as Code: Docker, Dev Container, GitHub workflows.
Capturing Essential Elements
• Configuration files (conf.py, ray_serving.yaml) as annotation in the infrastructure layer.
• Download.py and OneDrive/HF repository as external data sources feeding into conf.py and model server.
• Test coverage in mlib/test and CI workflow to show quality gates.