marketschema 1.1.0__tar.gz

marketschema-1.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: marketschema
+Version: 1.1.0
+Summary: Python SDK for the MarketSchema Public API v1
+Home-page: https://github.com/FlyingMobula5/MarketSchema
+Author: MarketSchema
+Author-email: api@marketschema.com
+Project-URL: Documentation, https://marketschema.com/docs
+Project-URL: Public API, https://marketschema.com/docs/api
+Project-URL: Source, https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Internet
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# MarketSchema Python SDK
+
+Official Python client for the [MarketSchema](https://marketschema.com) Public API v1 —
+structural market intelligence: schema scores, market-risk gauges, proprietary indexes,
+narratives, and themes, built for both humans and trading agents.
+
+## Install
+
+```bash
+pip install marketschema
+```
+
+## Quickstart
+
+```python
+from marketschema import MarketSchemaClient
+
+client = MarketSchemaClient(api_key="ms_...")  # mint a free key at marketschema.com/account/api-keys
+
+# Who am I / what can my key do?
+print(client.whoami())
+print(client.capabilities())
+
+# Single-asset intelligence packet
+nvda = client.asset("NVDA")
+print(nvda["schema_score"], nvda["regime_label"])
+
+# Batch check (paid tiers)
+result = client.batch(["NVDA", "MSFT", "SPY"])
+
+# Server-sent event stream of live updates
+for event in client.stream():
+    print(event)
+```
+
+## Agent / bot endpoints
+
+The SDK speaks the full bot contract — registration, heartbeats, snapshots,
+webhooks, and the paper/replay/shadow harnesses:
+
+```python
+client.register(name="my-bot", environment="paper")
+client.heartbeat(status="ok")
+client.webhook_register(url="https://example.com/hook", events=["score.changed"])
+```
+
+Complete, runnable agents live in
+[`examples/`](https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python/examples)
+(`paper_bot.py`, `replay_bot.py`, `shadow_bot.py`).
+
+## Auth, limits, errors
+
+- Auth is a single `X-API-Key` header — the client sets it for you.
+- Free tier: 1 key, 60 requests/min. Paid tiers raise key counts, rate
+  limits, and batch quotas — see [marketschema.com/pricing](https://marketschema.com/pricing).
+- Non-2xx responses raise `MarketSchemaError` with `.status_code` and the
+  parsed error envelope on `.response`.
+
+## Links
+
+- Docs: https://marketschema.com/docs
+- API reference: https://marketschema.com/docs/api
+- Source: https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python
+
+MIT licensed.

marketschema-1.1.0/README.md

@@ -0,0 +1,65 @@
+# MarketSchema Python SDK
+
+Official Python client for the [MarketSchema](https://marketschema.com) Public API v1 —
+structural market intelligence: schema scores, market-risk gauges, proprietary indexes,
+narratives, and themes, built for both humans and trading agents.
+
+## Install
+
+```bash
+pip install marketschema
+```
+
+## Quickstart
+
+```python
+from marketschema import MarketSchemaClient
+
+client = MarketSchemaClient(api_key="ms_...")  # mint a free key at marketschema.com/account/api-keys
+
+# Who am I / what can my key do?
+print(client.whoami())
+print(client.capabilities())
+
+# Single-asset intelligence packet
+nvda = client.asset("NVDA")
+print(nvda["schema_score"], nvda["regime_label"])
+
+# Batch check (paid tiers)
+result = client.batch(["NVDA", "MSFT", "SPY"])
+
+# Server-sent event stream of live updates
+for event in client.stream():
+    print(event)
+```
+
+## Agent / bot endpoints
+
+The SDK speaks the full bot contract — registration, heartbeats, snapshots,
+webhooks, and the paper/replay/shadow harnesses:
+
+```python
+client.register(name="my-bot", environment="paper")
+client.heartbeat(status="ok")
+client.webhook_register(url="https://example.com/hook", events=["score.changed"])
+```
+
+Complete, runnable agents live in
+[`examples/`](https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python/examples)
+(`paper_bot.py`, `replay_bot.py`, `shadow_bot.py`).
+
+## Auth, limits, errors
+
+- Auth is a single `X-API-Key` header — the client sets it for you.
+- Free tier: 1 key, 60 requests/min. Paid tiers raise key counts, rate
+  limits, and batch quotas — see [marketschema.com/pricing](https://marketschema.com/pricing).
+- Non-2xx responses raise `MarketSchemaError` with `.status_code` and the
+  parsed error envelope on `.response`.
+
+## Links
+
+- Docs: https://marketschema.com/docs
+- API reference: https://marketschema.com/docs/api
+- Source: https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python
+
+MIT licensed.

marketschema-1.1.0/examples/__init__.py

@@ -0,0 +1 @@
+# Sprint 17 (#94): Make examples package importable for `python -m examples.paper_bot`

marketschema-1.1.0/examples/paper_bot.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""MarketSchema Paper Bot — Live Polling Reference
+
+Canonical happy-path runner for paper-trading against the MarketSchema API.
+Uses the in-repo SDK and paper_bot adapter layer.
+
+Usage:
+    # Set your API key
+    export MS_API_KEY="ms_live_..."
+
+    # Run 10 cycles at 60-second intervals (default)
+    python -m examples.paper_bot
+
+    # Custom watchlist and cycle count
+    python -m examples.paper_bot --watchlist AAPL,MSFT,NVDA,TSLA --cycles 20 --interval 30
+
+    # With custom journal output
+    python -m examples.paper_bot --journal paper_decisions.jsonl
+
+Environment Variables:
+    MS_API_KEY      Required. Your MarketSchema API key.
+    MS_BASE_URL     Optional. API base URL (default: https://api.marketschema.com).
+
+Output:
+    - JSONL decision journal (default: output/paper_journal_{date}.jsonl)
+    - Summary printed to stderr after completion
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime, timezone
+
+# Allow running from sdk/python/ or repo root
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from marketschema import MarketSchemaClient
+from marketschema.paper_bot import PaperBotRunner
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="MarketSchema Paper Bot — live polling reference"
+    )
+    parser.add_argument(
+        "--watchlist",
+        default="SPY,QQQ,AAPL,MSFT,NVDA",
+        help="Comma-separated ticker watchlist (default: SPY,QQQ,AAPL,MSFT,NVDA)",
+    )
+    parser.add_argument(
+        "--cycles",
+        type=int,
+        default=10,
+        help="Number of polling cycles (default: 10)",
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=60,
+        help="Seconds between polls (default: 60)",
+    )
+    parser.add_argument(
+        "--horizon",
+        default="swing",
+        choices=["day", "swing", "position"],
+        help="Trading horizon for batch checks (default: swing)",
+    )
+    parser.add_argument(
+        "--style",
+        default=None,
+        help="Trading style for batch checks (e.g., momentum, mean_reversion)",
+    )
+    parser.add_argument(
+        "--journal",
+        default=None,
+        help="Journal output path (default: output/paper_journal_{date}.jsonl)",
+    )
+    parser.add_argument(
+        "--bot-name",
+        default="ms-paper-bot",
+        help="Bot registration name (default: ms-paper-bot)",
+    )
+    parser.add_argument(
+        "--strategy-label",
+        default=None,
+        help="Strategy label for bot registration",
+    )
+    args = parser.parse_args()
+
+    # Validate API key
+    api_key = os.environ.get("MS_API_KEY")
+    if not api_key:
+        print("ERROR: MS_API_KEY environment variable is required.", file=sys.stderr)
+        print("  export MS_API_KEY='ms_live_...'", file=sys.stderr)
+        sys.exit(1)
+
+    base_url = os.environ.get("MS_BASE_URL", "https://api.marketschema.com")
+
+    # Default journal path
+    journal_path = args.journal
+    if not journal_path:
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        journal_path = f"output/paper_journal_{today}.jsonl"
+
+    # Build client and runner
+    client = MarketSchemaClient(api_key=api_key, base_url=base_url)
+    watchlist = [t.strip() for t in args.watchlist.split(",")]
+
+    runner = PaperBotRunner.from_client(
+        client=client,
+        watchlist=watchlist,
+        horizon=args.horizon,
+        style=args.style,
+        journal_path=journal_path,
+        bot_name=args.bot_name,
+        strategy_label=args.strategy_label,
+    )
+
+    print(f"Paper Bot starting:", file=sys.stderr)
+    print(f"  Watchlist: {watchlist}", file=sys.stderr)
+    print(f"  Cycles:    {args.cycles}", file=sys.stderr)
+    print(f"  Interval:  {args.interval}s", file=sys.stderr)
+    print(f"  Journal:   {journal_path}", file=sys.stderr)
+    print(f"  Mode:      PAPER (no broker, no execution)", file=sys.stderr)
+    print(file=sys.stderr)
+
+    summary = runner.run(cycles=args.cycles, interval=args.interval)
+
+    print(file=sys.stderr)
+    print(f"Run complete. {summary['cycles_completed']} cycles logged to {journal_path}", file=sys.stderr)
+    if summary.get("setup_report_path"):
+        print(f"Setup report: {summary['setup_report_path']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

marketschema-1.1.0/examples/replay_bot.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""MarketSchema Replay Bot — Historical State Replay Reference
+
+Replays historical MarketSchema exports through the same paper-bot logic
+to validate integration behavior against known market states.
+
+Usage:
+    # Replay a saved history/daily export
+    python -m examples.replay_bot --source exports/history_2026-03-01_2026-03-07.json
+
+    # Fetch fresh history from the API, then replay
+    python -m examples.replay_bot --fetch --start 2026-03-01 --end 2026-03-07
+
+    # With custom journal output
+    python -m examples.replay_bot --source data.json --journal replay_output.jsonl
+
+Input Format:
+    The source JSON should match the /v1/history/daily response shape:
+    {
+      "start_date": "2026-03-01",
+      "end_date": "2026-03-07",
+      "rows": [
+        {
+          "date": "2026-03-01",
+          "conditions_state": { "gate": "open", "direction": "long", ... },
+          "gate_state": { "state": "open", "max_position_scale": 1.0, ... },
+          "posture_state": { "posture_state": "risk-on", "posture_score": 0.78, ... }
+        },
+        ...
+      ]
+    }
+
+Output:
+    - JSONL replay journal (default: output/replay_journal_{date}.jsonl)
+    - Per-step summary printed to stderr
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from marketschema import MarketSchemaClient
+from marketschema.paper_bot import PaperBotRunner
+
+
+def fetch_history(api_key: str, base_url: str, start: str, end: str, output: str) -> str:
+    """Fetch history/daily from the API and save to a local file.
+
+    NOTE: SDK v1.0.0 does not include history_daily() endpoint.
+    The --fetch option is no longer supported. Use --source to provide a pre-exported JSON file.
+    """
+    print("ERROR: --fetch is not supported in SDK v1.0.0", file=sys.stderr)
+    print("  The history_daily() method was removed from the public API.", file=sys.stderr)
+    print("  Use --source <path> to replay from a pre-exported JSON file instead.", file=sys.stderr)
+    raise RuntimeError("fetch_history not supported in v1.0.0")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="MarketSchema Replay Bot — historical state replay"
+    )
+    parser.add_argument(
+        "--source",
+        default=None,
+        help="Path to a history/daily JSON export file",
+    )
+    parser.add_argument(
+        "--fetch",
+        action="store_true",
+        help="Fetch history from the API first (requires MS_API_KEY)",
+    )
+    parser.add_argument(
+        "--start",
+        default=None,
+        help="Start date for --fetch (YYYY-MM-DD)",
+    )
+    parser.add_argument(
+        "--end",
+        default=None,
+        help="End date for --fetch (YYYY-MM-DD)",
+    )
+    parser.add_argument(
+        "--journal",
+        default=None,
+        help="Journal output path (default: output/replay_journal_{date}.jsonl)",
+    )
+    args = parser.parse_args()
+
+    # Determine source
+    source_path = args.source
+    if args.fetch:
+        api_key = os.environ.get("MS_API_KEY")
+        if not api_key:
+            print("ERROR: MS_API_KEY required for --fetch", file=sys.stderr)
+            sys.exit(1)
+        if not args.start or not args.end:
+            print("ERROR: --start and --end required for --fetch", file=sys.stderr)
+            sys.exit(1)
+        base_url = os.environ.get("MS_BASE_URL", "https://api.marketschema.com")
+        source_path = fetch_history(
+            api_key, base_url, args.start, args.end,
+            output=f"output/history_{args.start}_{args.end}.json",
+        )
+    elif not source_path:
+        print("ERROR: Provide --source <path> or --fetch --start ... --end ...", file=sys.stderr)
+        sys.exit(1)
+
+    # Default journal path
+    journal_path = args.journal
+    if not journal_path:
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        journal_path = f"output/replay_journal_{today}.jsonl"
+
+    print(f"Replay Bot starting:", file=sys.stderr)
+    print(f"  Source:  {source_path}", file=sys.stderr)
+    print(f"  Journal: {journal_path}", file=sys.stderr)
+    print(f"  Mode:    REPLAY (historical, no API calls)", file=sys.stderr)
+    print(file=sys.stderr)
+
+    runner = PaperBotRunner.from_replay(
+        source=source_path,
+        journal_path=journal_path,
+    )
+
+    summary = runner.run()
+
+    print(file=sys.stderr)
+    print(
+        f"Replay complete. {summary['cycles_completed']} steps logged to {journal_path}",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()

marketschema-1.1.0/examples/shadow_bot.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""MarketSchema Shadow Bot — Non-Executing Observation Mode
+
+Shadow mode runs the same decision logic as a live paper-trading bot,
+but does NOT execute any trades. All decisions are logged for later
+comparison against actual live executions, validating signal consistency.
+
+Usage:
+    # Set your API key
+    export MS_API_KEY="ms_live_..."
+
+    # Run 10 cycles at 60-second intervals (default)
+    python -m examples.shadow_bot
+
+    # Custom watchlist and cycle count
+    python -m examples.shadow_bot --watchlist AAPL,MSFT,NVDA,TSLA --cycles 20 --interval 30
+
+    # With custom journal output
+    python -m examples.shadow_bot --journal shadow_decisions.jsonl
+
+Environment Variables:
+    MS_API_KEY      Required. Your MarketSchema API key.
+    MS_BASE_URL     Optional. API base URL (default: https://api.marketschema.com).
+
+Output:
+    - JSONL decision journal (default: output/shadow_journal_{date}.jsonl)
+    - Summary printed to stderr after completion
+    - All journal entries marked with mode="shadow" and execution="withheld"
+
+Usage Patterns:
+    1. Run shadow_bot in parallel with live trading to compare decisions
+    2. Backtest shadow journals against historical data for validation
+    3. Use to validate signal consistency before production deployment
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime, timezone
+
+# Allow running from sdk/python/ or repo root
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from marketschema import MarketSchemaClient
+from marketschema.paper_bot import PaperBotRunner
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="MarketSchema Shadow Bot — non-executing observation mode"
+    )
+    parser.add_argument(
+        "--watchlist",
+        default="SPY,QQQ,AAPL,MSFT,NVDA",
+        help="Comma-separated ticker watchlist (default: SPY,QQQ,AAPL,MSFT,NVDA)",
+    )
+    parser.add_argument(
+        "--cycles",
+        type=int,
+        default=10,
+        help="Number of polling cycles (default: 10)",
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=60,
+        help="Seconds between polls (default: 60)",
+    )
+    parser.add_argument(
+        "--horizon",
+        default="swing",
+        choices=["day", "swing", "position"],
+        help="Trading horizon for batch checks (default: swing)",
+    )
+    parser.add_argument(
+        "--style",
+        default=None,
+        help="Trading style for batch checks (e.g., momentum, mean_reversion)",
+    )
+    parser.add_argument(
+        "--journal",
+        default=None,
+        help="Journal output path (default: output/shadow_journal_{date}.jsonl)",
+    )
+    parser.add_argument(
+        "--bot-name",
+        default="ms-shadow-bot",
+        help="Bot registration name (default: ms-shadow-bot)",
+    )
+    parser.add_argument(
+        "--strategy-label",
+        default=None,
+        help="Strategy label for bot registration",
+    )
+    args = parser.parse_args()
+
+    # Validate API key
+    api_key = os.environ.get("MS_API_KEY")
+    if not api_key:
+        print("ERROR: MS_API_KEY environment variable is required.", file=sys.stderr)
+        print("  export MS_API_KEY='ms_live_...'", file=sys.stderr)
+        sys.exit(1)
+
+    base_url = os.environ.get("MS_BASE_URL", "https://api.marketschema.com")
+
+    # Default journal path
+    journal_path = args.journal
+    if not journal_path:
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        journal_path = f"output/shadow_journal_{today}.jsonl"
+
+    # Build client and runner
+    client = MarketSchemaClient(api_key=api_key, base_url=base_url)
+    watchlist = [t.strip() for t in args.watchlist.split(",")]
+
+    runner = PaperBotRunner.from_client(
+        client=client,
+        watchlist=watchlist,
+        horizon=args.horizon,
+        style=args.style,
+        journal_path=journal_path,
+        bot_name=args.bot_name,
+        strategy_label=args.strategy_label,
+        environment="shadow",  # Shadow mode!
+    )
+
+    print(f"Shadow Bot starting:", file=sys.stderr)
+    print(f"  Watchlist: {watchlist}", file=sys.stderr)
+    print(f"  Cycles:    {args.cycles}", file=sys.stderr)
+    print(f"  Interval:  {args.interval}s", file=sys.stderr)
+    print(f"  Journal:   {journal_path}", file=sys.stderr)
+    print(f"  Mode:      SHADOW (observation only, no broker execution)", file=sys.stderr)
+    print(file=sys.stderr)
+
+    summary = runner.run(cycles=args.cycles, interval=args.interval)
+
+    print(file=sys.stderr)
+    print(f"Shadow run complete. {summary['cycles_completed']} cycles logged to {journal_path}", file=sys.stderr)
+    if summary.get("setup_report_path"):
+        print(f"Setup report: {summary['setup_report_path']}", file=sys.stderr)
+    print(file=sys.stderr)
+    print("Next steps:", file=sys.stderr)
+    print(f"  1. Compare this shadow journal with live trading journal:", file=sys.stderr)
+    print(f"     python -c \"from marketschema.paper_bot import compare_journals; ", file=sys.stderr)
+    print(f"     print(compare_journals('{journal_path}', 'live_journal.jsonl'))\"", file=sys.stderr)
+    print(f"  2. Analyze decision consistency and signal quality", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

marketschema-1.1.0/marketschema/__init__.py

@@ -0,0 +1,36 @@
+"""MarketSchema Python SDK v1.0.0 — Public API Client
+
+Lightweight, zero-dependency (beyond requests) client for the
+MarketSchema Public API v1. Provides access to 10 PUBLIC_KEEP endpoints:
+- Auth: whoami, capabilities, stream-token
+- Asset Packets: asset, batch
+- Delivery: stream, webhook_register, webhook_list, webhook_delete, webhook_test
+
+Usage:
+    from marketschema import MarketSchemaClient
+
+    client = MarketSchemaClient(api_key="ms_...")
+
+    # Verify identity
+    identity = client.whoami()
+    print(f"Plan: {identity['plan']}")
+
+    # Get schema score for a ticker
+    score = client.asset("AAPL")
+    print(f"AAPL schema score: {score['schema_score']['score']}")
+
+    # Batch check multiple tickers
+    batch = client.batch(tickers=["MSFT", "GOOGL", "TSLA"])
+
+    # Register webhook for score changes
+    webhook = client.webhook_register("https://example.com/webhook")
+
+    # Stream live updates
+    for event in client.stream():
+        print(event)
+"""
+
+from marketschema.client import MarketSchemaClient
+
+__version__ = "1.1.0"
+__all__ = ["MarketSchemaClient"]