MainSequence Markets

ms-markets is the financial markets extension layer for the Main Sequence platform. It provides reusable market-domain ORM models, market time-index updaters, portfolio construction utilities, repository operations, and application-facing helpers for building financial systems on top of Main Sequence. Portfolio and QuantLib-backed pricing capabilities are packaged as separate import surfaces so core msm stays focused on shared markets primitives.

The Python distribution is named ms-markets. The core import package is intentionally short:

import msm

Portfolio workflows import from msm_portfolios. Optional QuantLib-backed pricing imports from msm_pricing.

Project Status

• Status: initial scaffold and SDK extraction
• Current release line: 2.x
• Documentation: Documentation Site
• Open issues: GitHub Issues
• Release history: CHANGELOG.md
• License: Apache License 2.0

The initial core package was migrated from mainsequence-sdk/mainsequence/markets into this repository under src/msm. Architecture and implementation decisions are tracked in Architecture Decision Records.

What This Repository Contains

Main package areas:

• msm.api.accounts: account identity and account target assignment row APIs
• msm.api.calendars: calendar identity, date, session, and event row APIs
• msm.api: user-facing Pydantic row objects and typed class methods for markets MetaTable records
• msm.api.http: installable provider-neutral collection, discovery, bulk-preflight, tabular-frame, observable-operation, and structured-error contracts
• msm.constants: static built-in keys such as asset type constants used across applications and examples
• msm.client: client for the Markets API (ADR 0047, decision 2). Its remote backend runs the same msm.api row calls through the API, so an application needs no MetaTables grant on mainsequence.markets
• msm.time_index: market TimeIndexTableUpdater contracts, including account holdings, execution events, asset snapshots, and asset pricing details
• msm.api.execution: order managers, target quantities, orders, events, trades, and execution error row APIs
• msm.models: SQLAlchemy market-domain *Table declarations and MetaTable registration order
• msm_portfolios: portfolio configuration, signal weights, rebalance strategies, virtual funds, and portfolio construction workflows
• msm_pricing: optional QuantLib-backed instruments, curves, fixings, pricing helpers, and pure-data analytics installed with pricing or analytics extras
• msm.repositories: compiled persistence operations over market-domain models
• msm.services: application-level orchestration over repositories, including asset lookup and OpenFIGI service helpers
• msm CLI: package maintenance helpers such as explicit agent-skill copying; MetaTable migrations run through the metatables migrations CLI with --provider msm_migrations:migration

Repository areas:

• docs/: MkDocs documentation, tutorials, knowledge guides, ADRs, and API reference scaffold
• examples/msm/: core assets, accounts, calendars, formula/custom indexes, platform, and row-workflow examples
• examples/msm_portfolios/: portfolio construction, rebalance simulation, lifecycle cash-flow, multi-currency valuation, and accounting examples
• examples/msm_pricing/: optional pricing and QuantLib-backed examples
• .agents/skills/ms_markets/: source agent skills for market-domain workflows
• tests/: automated tests

Documentation Map

The documentation is organized into four reading modes:

1. Tutorial: guided learning material
2. Knowledge: concept-oriented guides for each msm package area
3. Architecture: ADRs that record implementation decisions
4. Reference: generated API reference scaffold

Recommended entry points:

• Getting Started
• Tutorial
• FastAPI v1
• Knowledge Base
• Architecture Decision Records
• Changelog
• API Reference

Quick Start

ms-markets 2.x requires Python 3.13, Main Sequence SDK >=9.0.29,<10, and the MetaTables client mainsequence-metatable>=0.1.51,<0.2, which is imported as metatables. SDK 8 and earlier are not supported; install a 1.x ms-markets release when maintaining an SDK 8 project. See ADR 0043 and the 2.0.0 changelog entry for the breaking changes.

Install the package from this repository in editable mode:

python -m pip install -e ".[dev]"

Or with uv:

uv sync --extra dev

Install pricing support only when needed:

uv sync --extra pricing

Install the named analytics surface when working with optional spread analytics:

uv sync --extra analytics

Install portfolio workflow support only when needed:

uv sync --extra portfolios

Install the project-level FastAPI surface only when needed:

uv sync --extra public_api

Verify the core import:

python -c "import msm; print(msm.__version__)"

Provider APIs can import the shared HTTP toolkit directly from the wheel:

from msm.api.http import ResourceCollection, api_http_error

After installing the pricing extra, verify the optional pricing import:

python -c "import msm_pricing; print(msm_pricing.FixedRateBond)"

Copy the packaged ms-markets skills into a host Main Sequence CodeRepository only when you explicitly want them available to agents in that repository:

msm copy-msm-skills --path /path/to/code-repository

Importing msm never mutates the current directory or auto-copies skills. The command writes only to <code-repository>/.agents/skills/ms_markets/ and leaves unrelated .agents content alone. Use --dry-run or --json to inspect the copy plan.

Common Development Commands

Run tests:

pytest

Run focused linting for optional pricing:

ruff check src/msm_pricing

Serve the docs locally:

mkdocs serve

Build the docs:

mkdocs build --strict

Build the package:

uv build

Releases are published by GitHub Actions, never by hand. Work lands on the development branch, where every push publishes an X.Y.Z.devN build to PyPI. main is protected: merging a pull request from development publishes the declared X.Y.Z, creates its vX.Y.Z tag and deploys the documentation. See Releasing.

Core Dependencies

Runtime dependencies are declared in pyproject.toml. The core stack starts with:

• mainsequence>=9.0.29,<10 for identity, login, Git source context, CodeRepository, jobs, and agents
• mainsequence-metatable>=0.1.51,<0.2 (import metatables) for MetaTables, time-index table updaters, governed compiled SQL, and application-owned Alembic migrations
• SQLAlchemy for market-domain ORM models
• pydantic for typed configuration and serialized row contracts
• pandas and numpy for tabular market data

Optional extras provide analytics, documentation, development, portfolio, public API, and pricing tooling. The analytics and pricing-analytics extras reserve the dependency boundary for optional analytics helpers; the current spread helpers use the core numpy and pandas dependencies. The portfolios extra installs portfolio-only helpers such as pandas-market-calendars. The public_api extra installs FastAPI and Uvicorn for the project-level apps/v1 surface. The pricing extra installs QuantLib and the optional pricing runtime exposed as msm_pricing.

Package Metadata

• Distribution name: ms-markets
• Import packages: msm, msm_portfolios, and optional msm_pricing
• Provider HTTP toolkit: msm.api.http
• Python: >=3.13,<3.14
• License: Apache-2.0
• Repository: https://github.com/mainsequence-projects/MainSequenceMarkets

Project metadata is defined in pyproject.toml.

License

This project is open source under the Apache License 2.0.