Refactor SDK packaging for public release

Author: jaws777

.dockerignore

@@ -0,0 +1,20 @@
+.git
+.github
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+__pycache__
+*.egg-info
+*.pyc
+*.pyo
+*.pyd
+.DS_Store
+.env
+api/.env
+artifacts
+build
+coverage.xml
+dist
+htmlcov
+hypercore_feed_compare.json

.github/workflows/ci.yml

@@ -1,40 +1,33 @@
-name: CI
+name: ci
 
 on:
   push:
-    branches:
-      - main
+    branches: ["main", "master"]
   pull_request:
 
 jobs:
-  validate:
+  test:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.12"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev]"
+          python -m pip install -e '.[dev]'
 
       - name: Run tests
-        run: pytest -q
+        run: pytest
 
       - name: Run mypy
         run: mypy -p hypercore_sdk
 
       - name: Build package
         run: python -m build
 
-      - name: Check package metadata
+      - name: Validate distribution metadata
         run: python -m twine check dist/*

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Release
+name: release
 
 on:
   push:
@@ -11,34 +11,27 @@ jobs:
     permissions:
       contents: write
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev]"
+          python -m pip install -e '.[dev]'
 
-      - name: Run tests
-        run: pytest -q
-
-      - name: Run mypy
-        run: mypy -p hypercore_sdk
-
-      - name: Build package
-        run: python -m build
-
-      - name: Check package metadata
-        run: python -m twine check dist/*
+      - name: Validate release
+        run: |
+          pytest
+          mypy -p hypercore_sdk
+          python -m build
+          python -m twine check dist/*
 
       - name: Publish GitHub release
         uses: softprops/action-gh-release@v2
         with:
-          generate_release_notes: true
           files: |
-            dist/*
+            dist/*.whl
+            dist/*.tar.gz

API_interface.md

@@ -1,4 +1,4 @@
-# HyperCore SDK API Interface Reference
+# Aleatoric Hypercore Python SDK API Interface Reference
 
 This document is the interface contract for the Python SDK in this repository.
 
@@ -9,19 +9,19 @@ Scope:
 - Status API client and stdio MCP server
 - Derived intelligence layer for indexing and analytics
 
-As-of validation (March 7, 2026):
 As-of validation (March 13, 2026):
-- `pytest`: **127 passed**
-- `pytest` with coverage gate: **92.45% total coverage**
+- `pytest`: **128 passed**
+- `pytest` with coverage gate: **93.22% total coverage**
 - `mypy -p hypercore_sdk`: **no issues found** (16 source files)
-- `python -m build`: **passed**
+- `python -m build --no-isolation`: **passed**
 - `python -m twine check dist/*`: **passed**
 
 ## 1. Quality, Guarantees, and Limits
 
 Objective quality facts:
 - The package is typed (`py.typed`) and mypy-clean under project settings.
 - CLI command paths are unit tested with mocked dependencies.
+- MCP tools are contract-tested across the full published tool matrix.
 - Core adapters validate response shapes and raise `RuntimeError` on incompatible payloads.
 - Coverage is above enforced gate (90%).
 
@@ -215,6 +215,10 @@ Current MCP tools:
 - `status_get_private`
 - `rpc_call`
 
+Operational contract notes:
+- The MCP tool names above are the supported outward-facing interface for editor and agent integrations.
+- Python MCP argument names use snake_case, matching the Python CLI and Python method naming.
+
 ## 5. WebSocket Interface
 
 File: `hypercore_sdk/ws.py`

CHANGELOG.md

@@ -2,69 +2,28 @@
 
 All notable changes to this project are documented in this file.
 
-## [0.3.0] — 2026-03-13
+## [0.3.0] - 2026-03-13
 
 ### Added
-- Browser-safe unified client parity for:
-  - `all_mids()` / `sse_all_mids()`
-  - `l2_book()` / `sse_l2_book()`
-  - `asset_contexts()` / `sse_asset_contexts()`
-- Unified `consensus_pulse()` client method.
-- Status API client:
-  - `hypercore_sdk/status.py`
-- Python stdio MCP server:
-  - `hypercore_sdk/mcp.py`
-  - `hypercore_sdk/mcp_cli.py`
-- Tests for unified snapshot/SSE parity, status client, and MCP server:
-  - `tests/test_unified_stream.py`
-  - `tests/test_status.py`
-  - `tests/test_mcp.py`
-  - `tests/test_cli.py`
-- Dedicated liquidation support in client and examples (`StreamLiquidations` path), plus unified `liquidation_cascade` helpers and MCP passthrough.
-- Provider matrix benchmark option for liquidation feed benchmarking.
-- Project tracking docs:
-  - `PROJECT_STATE.md`
-  - `AGENTS.md`
-- Container deployment artifacts:
-  - `Dockerfile`
-  - `docker-compose.yml`
-  - `DEPLOYMENT.md`
-- Auth/key-scope preflight utility: `examples/preflight_feed_auth.py` for rpc/unified/disk-ws/grpc validation.
-- Provider benchmark JSON template now includes scoped key wiring guidance for gRPC vs unified/disk streams.
-- Live gRPC console example for side-by-side `l2Book` and `trades` bridge feeds (`examples/grpc_l2book_trades_console.py`).
+
+- Public package metadata for Python distribution, including license, authors, URLs, classifiers, and package manifest controls.
+- Customer-facing documentation, contribution guide, and a basic connection example.
+- Refreshed API interface reference for external consumers and support handoff.
+- GitHub Actions workflows for CI and tagged releases.
+- Browser-safe unified stream parity for all-mids, L2 book, and asset contexts.
+- Status API client, stdio MCP server, and expanded test coverage.
 
 ### Changed
-- `hypercore_sdk/cli.py` now exposes unified commands for `consensus-pulse`, `all-mids`, `l2-book`, `asset-contexts`, `liquidations`, and `cascades`.
-- README and API reference now document the Python MCP server and the browser-safe unified interfaces.
-- Unified stream client query construction was cleaned up to remove repeated ad hoc param-building paths while keeping request semantics unchanged.
-- Feed benchmark split between market WS and disk-sync WS.
-- README setup/troubleshooting now documents virtualenv-first install flow.
-- `.gitignore` expanded for coverage, caches, local outputs, and egg metadata.
-- Default endpoint targets updated to Aleatoric stream infrastructure:
-  - Market/disk WS default `wss://disk.grpc.aleatoric.systems/`
-  - Unified API default `https://unified.grpc.aleatoric.systems`
-  - gRPC default `hl.grpc.aleatoric.systems:443`
-- Feed latency benchmark now records per-attempt audit stamps, metric-kind summaries, and event-age stats where source timestamps exist.
-- Key selection hardened across feed benchmark, matrix runner, and preflight script to ignore malformed placeholder keys and prefer RPC-scoped keys for gRPC checks.
-- Provider benchmark and auth preflight output now make scoped endpoint auth failures explicit, reducing false attribution of partial-provider results to latency regressions.
-- Example credential loading and scoped key selection are now centralized in `hypercore_sdk/example_auth.py`, removing drift across benchmark, preflight, provider-matrix, and gRPC live examples.
-- Benchmark and preflight HTTP checks now classify upstream `502/503/504` responses as `upstream_unavailable`, and feed benchmark output now includes `auth_key_sources` plus `availability_alerts`.
-- Feed benchmark output is now typed via `hypercore_sdk/benchmark_models.py`, supports `--profile-json` / `--out-json`, ships reproducible benchmark profiles plus March 10, 2026 baseline snapshots, and can emit machine-readable availability exit codes.
-- `examples/grpc_l2book_trades_console.py` now:
-  - reports which key source it selected
-  - runs gRPC health and `PriceService` preflight before streaming
-  - renders compact gRPC auth-preflight failures instead of raw `_InactiveRpcError` blobs
-  - fails fast with a clear diagnosis when `PriceService` access returns `403/PERMISSION_DENIED`, including the broader case where health and stream RPCs are both denied by the endpoint
-- gRPC live examples now prefer `ALEATORIC_GRPC_KEY` and RPC-scoped keys before `GRPC_STREAM_KEY` / `UNIFIED_STREAM_KEY`, fixing false `403` failures in mixed-key environments.
-- README and project-state docs now explain how to distinguish local key-selection drift from endpoint-side gRPC authorization failures.
-- README and deployment docs now formalize the containerized SDK runtime/build model and explicitly scope out the external bridge server.
-- CI and release automation now run tests, mypy, package builds, and `twine check` for push/PR validation and tagged releases.
-- CI now also builds Docker `runtime`/`dev` targets, validates `docker-compose.yml`, runs a containerized CLI smoke, and tagged releases publish the runtime image to GHCR.
-- `AGENTS.md` now requires packaging validation alongside the existing gRPC local-vs-endpoint auth verification rules.
 
-## [0.3.0] - 2026-03-08
+- Reframed the repository as a public Aleatoric Systems SDK for external customers.
+- Standardized release validation around `pytest`, `mypy`, `python -m build`, and `twine check`.
+- Rewrote the README around installation, authentication, examples, release flow, and support.
+- Expanded MCP tests to treat the published tool matrix as a contract.
+
+## [0.2.0] - 2026-03-08
 
 ### Added
-- Read-only SDK architecture for RPC, WS, gRPC, unified stream, and high-value info surfaces.
-- CLI command groups for `price`, `intel`, `rpc`, `stream`, `grpc`, and `speed`.
-- Example scripts for auth preflight, latency benchmarking, and live stream consumers.
+
+- Read-only SDK architecture for RPC, WebSocket, gRPC, unified stream, and higher-level info surfaces.
+- CLI commands for `price`, `intel`, `rpc`, `stream`, `grpc`, and `speed`.
+- Example scripts for auth preflight, live streams, and benchmark workflows.

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Scope
+
+This repository is a customer-facing, read-only SDK for Aleatoric Hypercore services. Do not introduce signing, custody, or order-placement behavior.
+
+## Workflow
+
+1. Align on public API changes before implementation.
+2. Preserve backward compatibility unless a versioned breaking change is explicitly approved.
+3. Update tests, `README.md`, and `CHANGELOG.md` in the same pull request.
+4. Keep examples runnable from the repository root.
+
+## Local Validation
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+pytest
+mypy -p hypercore_sdk
+python -m build
+python -m twine check dist/*
+```
+
+## Support
+
+- Email: [github@aleatoric.systems](mailto:github@aleatoric.systems)
+- Discord: request the current customer support invite from the Aleatoric Systems team

DEPLOYMENT.md

@@ -0,0 +1,100 @@
+# Deployment Model
+
+This repository can be containerized end-to-end for the SDK, CLI, examples, benchmarks, and package build flow.
+
+It does not contain the upstream Aleatoric bridge server itself. The containerized surface here is:
+
+- `hypercore-sdk` CLI
+- runnable example scripts in `examples/`
+- benchmark and preflight tooling
+- Python package build and validation
+
+It does not deploy:
+
+- the Hyperliquid public WebSocket service
+- the Aleatoric gRPC bridge service
+- any signing, trading, or custody infrastructure
+
+## Images
+
+The repo now ships a multi-stage [Dockerfile](Dockerfile):
+
+- `runtime`: installs the package and exposes `hypercore-sdk`
+- `dev`: adds test/build tooling for `pytest`, `mypy`, `build`, and `twine`
+
+GitHub Actions CI now builds both targets on push/PR, and tagged releases publish the `runtime` image to GHCR.
+
+Build locally:
+
+```bash
+cd /Users/jaws/research/dev/aleatoric/public/hypercore-python-sdk
+docker build --target runtime -t hypercore-sdk:runtime .
+docker build --target dev -t hypercore-sdk:dev .
+```
+
+## Runtime Configuration
+
+Do not bake secrets into the image. Pass them at runtime with shell environment or `docker compose --env-file .env ...`.
+
+Relevant variables include:
+
+- `ALEATORIC_GRPC_TARGET`
+- `ALEATORIC_GRPC_SERVER_NAME`
+- `ALEATORIC_GRPC_KEY`
+- `RPC_GATEWAY_KEY`
+- `RPC_KEY`
+- `HYPER_API_KEY`
+- `ALEATORIC_MARKET_WS_KEY`
+- `UNIFIED_STREAM_KEY`
+
+The example scripts still honor the same key alias logic implemented in [hypercore_sdk/example_auth.py](hypercore_sdk/example_auth.py).
+
+## Compose Services
+
+[docker-compose.yml](docker-compose.yml) formalizes the common flows:
+
+- `cli`: run arbitrary `hypercore-sdk` commands
+- `ws-console`: live public WebSocket ladder + trades console
+- `grpc-console`: live gRPC `l2Book` + `trades` console
+- `benchmark`: feed latency benchmark with JSON output written to `./artifacts`
+- `validate`: repo quality gates inside the `dev` image
+- `package`: build wheel/sdist into `./dist`
+
+Examples:
+
+```bash
+cd /Users/jaws/research/dev/aleatoric/public/hypercore-python-sdk
+
+docker compose run --rm cli price ws --coin BTC
+
+docker compose --env-file .env run --rm ws-console
+
+docker compose --env-file .env run --rm grpc-console --coin BTC --max-events 20
+
+docker compose --env-file .env run --rm benchmark --coin BTC --runs 5 --skip-unified
+
+docker compose run --rm validate
+
+docker compose run --rm package
+```
+
+## Network Boundary
+
+These containers are outbound-only clients. No inbound ports are required.
+
+If the gRPC endpoint is only reachable over VPN, the host VPN must already be connected before starting the container. On Docker Desktop, verify that container traffic can traverse the VPN; otherwise `grpc-console` will fail with `StatusCode.UNAVAILABLE` even if the same command works on the host shell.
+
+## Recommended Deployment Pattern
+
+For local/operator use:
+
+1. Build the `runtime` image once.
+2. Pass credentials with `docker compose --env-file .env`.
+3. Run `grpc-console` or `benchmark` as short-lived jobs.
+4. Use `validate` in CI-equivalent checks before publishing package artifacts.
+
+For automation:
+
+1. Keep this image as a client/tooling container.
+2. Treat the Aleatoric gRPC bridge and unified feeds as external dependencies.
+3. Monitor network/VPN reachability separately from SDK correctness.