alloc-context 0.1.1__tar.gz → 0.2.0__tar.gz

alloc_context-0.2.0/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

{alloc_context-0.1.1 → alloc_context-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.1.1
-Summary: AllocContext — BTC/ETH allocation context, drift, and rebalance facts
-License: MIT
+Version: 0.2.0
+Summary: Portfolio-aware crypto context for agents — holdings, market, optional allocation analysis
+License: Elastic-2.0
 Project-URL: Homepage, https://github.com/negillett/alloc-context
 Project-URL: Documentation, https://github.com/negillett/alloc-context/blob/main/docs/agent-integration.md
 Project-URL: Repository, https://github.com/negillett/alloc-context
@@ -12,7 +12,6 @@ Project-URL: MCP Server, https://mcp.alloc-context.com/mcp
 Keywords: mcp,x402,bitcoin,ethereum,portfolio,allocation,agents,crypto,rebalance
 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.11
 Classifier: Programming Language :: Python :: 3.12
@@ -34,6 +33,9 @@ Requires-Dist: cdp-sdk>=1.46; extra == "hosted"
 Requires-Dist: uvicorn[standard]>=0.30; extra == "hosted"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: bandit>=1.8; extra == "dev"
+Requires-Dist: pip-audit>=2.9; extra == "dev"
 Requires-Dist: mcp>=1.6; extra == "dev"
 Requires-Dist: x402[evm,fastapi]>=2.0; extra == "dev"
 Requires-Dist: cdp-sdk>=1.46; extra == "dev"
@@ -44,16 +46,63 @@ Dynamic: license-file
 
 mcp-name: io.github.negillett/alloc-context
 
-**Allocation context for BTC/ETH** — drift, band checks, USD rebalance moves,
-and a fused market backdrop (Fear & Greed, Kalshi, ETF flows, macro) as
-deterministic JSON over MCP.
+**Portfolio-aware crypto context for agents** — discover holdings, market,
+sentiment, macro, and regime; optional allocation analysis. Deterministic
+JSON over MCP with x402 pay-per-call on Base.
 
-The product is an **agent-native MCP API** with x402 pay-per-call on Base —
-see [docs/mcp.md](docs/mcp.md).
+> **Privacy:** nothing stored · one-time read-only · pass-through only — your
+> keys and portfolio never persist on our servers. See [USE.md](docs/USE.md).
 
-## Hosted MCP (production)
+## Quick start (Cursor)
 
-Try the public endpoint without self-hosting:
+**1. Install**
+
+```bash
+pip install "alloc-context[mcp,hosted]"
+# From source: pip install -e ".[mcp,hosted]"
+```
+
+**2. User config**
+
+Copy [config/user.example.yaml](config/user.example.yaml) to
+`~/.config/alloc-context/user.yaml`. Add read-only exchange keys for portfolio
+discovery (optional) and an x402 payer for hosted market context. See
+[user-config.md](docs/user-config.md).
+
+**3. MCP config**
+
+Add to your Cursor `mcp.json` (or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "alloc-context": {
+      "command": "alloc-context",
+      "args": [
+        "mcp",
+        "--user-config",
+        "/Users/you/.config/alloc-context/user.yaml"
+      ]
+    }
+  }
+}
+```
+
+Use an absolute path for `--user-config`. Example:
+[cursor-mcp-bridge.example.json](docs/cursor-mcp-bridge.example.json).
+
+**4. Ask your agent**
+
+Call `get_context_bundle` for a full snapshot (holdings when keys are set,
+market/sentiment/macro via hosted upstream). Pure math tools
+(`check_allocation_band`, `get_rebalance_plan`) work without exchange keys.
+
+Full setup guide: [cursor-mcp.md](docs/cursor-mcp.md). Sample responses:
+[examples.md](docs/examples.md).
+
+Not financial advice.
+
+## Hosted MCP
 
 | | |
 |--|--|
@@ -62,31 +111,37 @@ Try the public endpoint without self-hosting:
 | **Pricing** | **$0.02** cached context/math · **$0.05** live ingest or portfolio |
 | **Payment** | x402 on Base — USDC or EURC |
 
-Agents find the service via [CDP Bazaar](docs/mcp-discovery.md). Integration
-guide: [docs/agent-integration.md](docs/agent-integration.md). Example JSON:
-[docs/examples.md](docs/examples.md).
+Agents and wallets connect directly to the hosted endpoint — see
+[agent-integration.md](docs/agent-integration.md). The Cursor bridge above
+combines local portfolio reads with this upstream for market context.
 
-**Try free locally** (no payment): `./scripts/dev-up.sh` — see
-[docs/local-dev.md](docs/local-dev.md).
+## MCP tools
 
-Optional live portfolio reads use read-only exchange credentials passed in
-each request. Not financial advice.
+| Tool | Purpose |
+|------|---------|
+| `get_context_bundle` | Full ContextBundle — holdings, market, sentiment, macro, delta, regime; optional `allocation_analysis` |
+| `get_market_context` | Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
+| `get_context_at` | Saved snapshot from ingest history at a given `as_of` |
+| `get_context_delta` | Notable shifts between two saved snapshots |
+| `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
+| `check_allocation_band` | Drift vs target and whether allocation is outside the band |
+| `check_allocation_bands` | Batch band checks for multiple target scenarios |
+| `get_portfolio_state` | Live NAV and holdings from Kraken or Coinbase |
 
-```text
-ingest → store → rollup → MCP tools (+ optional x402 HTTP)
-```
+See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 
-This package is **facts and MCP only** — ingest, rollups, and agent tools.
-Email, LLM synthesis, and alert delivery are out of scope for this repository.
+## Self-host and development
 
-## Try it locally
+Run ingest and MCP entirely on your machine — no x402 upstream required.
+See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config)
+or [local-dev.md](docs/local-dev.md) for the dev stack.
 
 ```bash
 git clone git@github.com:negillett/alloc-context.git
 cd alloc-context
 python3.11 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
-cp .env.example .env          # fill locally; never commit
+cp .env.example .env
 cp config/config.example.yaml config/config.yaml
 
 python -m alloccontext ingest --dry-run
@@ -94,19 +149,6 @@ python -m alloccontext rollup --scope daily --stdout
 pytest
 ```
 
-**MCP (stdio):** `pip install -e ".[mcp]"` then `alloc-context mcp`.
-See [docs/cursor-mcp.md](docs/cursor-mcp.md).
-
-**Hosted MCP + x402:** `pip install -e ".[hosted]"` then
-`alloc-context mcp --transport http --x402`. See [docs/mcp-http.md](docs/mcp-http.md).
-
-**Local dev stack (internal MCP on :8001):** `./scripts/dev-up.sh`.
-See [docs/local-dev.md](docs/local-dev.md).
-
-CLI entry point: `alloc-context` (same as `python -m alloccontext`).
-
-## Commands
-
 | Command | Purpose |
 |---------|---------|
 | `python -m alloccontext ingest` | Pull configured sources → SQLite |
@@ -114,37 +156,29 @@ CLI entry point: `alloc-context` (same as `python -m alloccontext`).
 | `python -m alloccontext status` | Per-source ingest ages, snapshots, MCP `/health` |
 | `alloc-context mcp` | MCP server (stdio or HTTP) |
 
-## MCP tools
-
-| Tool | Purpose |
-|------|---------|
-| `get_context_bundle` | Full ContextBundle — portfolio, market, sentiment, macro, delta, regime |
-| `get_market_context` | Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
-| `get_context_at` | Saved snapshot from ingest history at a given `as_of` |
-| `get_context_delta` | Notable shifts between two saved snapshots |
-| `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
-| `check_allocation_band` | Drift vs target and whether allocation is outside the band |
-| `check_allocation_bands` | Batch band checks for multiple target scenarios |
-| `get_portfolio_state` | Live NAV and allocation from Kraken or Coinbase (credentials in request) |
-
-See [docs/mcp.md](docs/mcp.md) for arguments, pricing, and resources.
+HTTP MCP + x402: [mcp-http.md](docs/mcp-http.md). CLI entry point:
+`alloc-context` (same as `python -m alloccontext`).
 
 ## Documentation
 
 | Document | Purpose |
 |----------|---------|
+| [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP (bridge default) |
+| [docs/user-config.md](docs/user-config.md) | Bridge `user.yaml` reference |
 | [docs/mcp.md](docs/mcp.md) | MCP tools and x402 |
-| [docs/mcp-http.md](docs/mcp-http.md) | HTTP MCP + x402 setup |
-| [docs/mcp-discovery.md](docs/mcp-discovery.md) | Bazaar and agent discovery |
-| [docs/distribution.md](docs/distribution.md) | GitHub, PyPI, MCP Registry, directories |
 | [docs/agent-integration.md](docs/agent-integration.md) | Paid HTTP MCP + Bazaar for agents |
-| [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP |
 | [docs/examples.md](docs/examples.md) | Sample tool JSON (redacted) |
 | [docs/context-bundle.md](docs/context-bundle.md) | ContextBundle schema |
-| [docs/architecture.md](docs/architecture.md) | Pipeline and trust boundaries |
-| [docs/data-sources.md](docs/data-sources.md) | Ingest sources |
+| [docs/USE.md](docs/USE.md) | Self-host vs hosted MCP (plain language) |
+| [docs/mcp-http.md](docs/mcp-http.md) | HTTP MCP + x402 setup |
+| [docs/mcp-discovery.md](docs/mcp-discovery.md) | Bazaar and agent discovery |
 | [docs/self-hosting.md](docs/self-hosting.md) | Optional Linux/systemd ingest + MCP |
 | [docs/local-dev.md](docs/local-dev.md) | Local internal MCP + dev ingest |
+| [docs/architecture.md](docs/architecture.md) | Pipeline and trust boundaries |
+| [docs/data-sources.md](docs/data-sources.md) | Ingest sources |
+| [docs/distribution.md](docs/distribution.md) | GitHub, PyPI, MCP Registry, directories |
+| [docs/publishing.md](docs/publishing.md) | Release workflow and version bumps |
+| [docs/security-ci.md](docs/security-ci.md) | CI coverage, Bandit, and pip-audit gates |
 
 ## Contributing
 
@@ -153,4 +187,7 @@ Unsolicited pull requests are not expected — see [CONTRIBUTING.md](CONTRIBUTIN
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+[Elastic License 2.0](LICENSE) — source-available, self-host friendly. See
+[docs/USE.md](docs/USE.md) for plain-language allowed uses.
+
+**Official hosted MCP:** `https://mcp.alloc-context.com/mcp`

alloc_context-0.2.0/README.md

@@ -0,0 +1,149 @@
+# AllocContext
+
+mcp-name: io.github.negillett/alloc-context
+
+**Portfolio-aware crypto context for agents** — discover holdings, market,
+sentiment, macro, and regime; optional allocation analysis. Deterministic
+JSON over MCP with x402 pay-per-call on Base.
+
+> **Privacy:** nothing stored · one-time read-only · pass-through only — your
+> keys and portfolio never persist on our servers. See [USE.md](docs/USE.md).
+
+## Quick start (Cursor)
+
+**1. Install**
+
+```bash
+pip install "alloc-context[mcp,hosted]"
+# From source: pip install -e ".[mcp,hosted]"
+```
+
+**2. User config**
+
+Copy [config/user.example.yaml](config/user.example.yaml) to
+`~/.config/alloc-context/user.yaml`. Add read-only exchange keys for portfolio
+discovery (optional) and an x402 payer for hosted market context. See
+[user-config.md](docs/user-config.md).
+
+**3. MCP config**
+
+Add to your Cursor `mcp.json` (or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "alloc-context": {
+      "command": "alloc-context",
+      "args": [
+        "mcp",
+        "--user-config",
+        "/Users/you/.config/alloc-context/user.yaml"
+      ]
+    }
+  }
+}
+```
+
+Use an absolute path for `--user-config`. Example:
+[cursor-mcp-bridge.example.json](docs/cursor-mcp-bridge.example.json).
+
+**4. Ask your agent**
+
+Call `get_context_bundle` for a full snapshot (holdings when keys are set,
+market/sentiment/macro via hosted upstream). Pure math tools
+(`check_allocation_band`, `get_rebalance_plan`) work without exchange keys.
+
+Full setup guide: [cursor-mcp.md](docs/cursor-mcp.md). Sample responses:
+[examples.md](docs/examples.md).
+
+Not financial advice.
+
+## Hosted MCP
+
+| | |
+|--|--|
+| **URL** | `https://mcp.alloc-context.com/mcp` |
+| **Discovery** | [llms.txt](https://mcp.alloc-context.com/llms.txt), [x402 manifest](https://mcp.alloc-context.com/.well-known/x402.json) |
+| **Pricing** | **$0.02** cached context/math · **$0.05** live ingest or portfolio |
+| **Payment** | x402 on Base — USDC or EURC |
+
+Agents and wallets connect directly to the hosted endpoint — see
+[agent-integration.md](docs/agent-integration.md). The Cursor bridge above
+combines local portfolio reads with this upstream for market context.
+
+## MCP tools
+
+| Tool | Purpose |
+|------|---------|
+| `get_context_bundle` | Full ContextBundle — holdings, market, sentiment, macro, delta, regime; optional `allocation_analysis` |
+| `get_market_context` | Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
+| `get_context_at` | Saved snapshot from ingest history at a given `as_of` |
+| `get_context_delta` | Notable shifts between two saved snapshots |
+| `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
+| `check_allocation_band` | Drift vs target and whether allocation is outside the band |
+| `check_allocation_bands` | Batch band checks for multiple target scenarios |
+| `get_portfolio_state` | Live NAV and holdings from Kraken or Coinbase |
+
+See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
+
+## Self-host and development
+
+Run ingest and MCP entirely on your machine — no x402 upstream required.
+See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config)
+or [local-dev.md](docs/local-dev.md) for the dev stack.
+
+```bash
+git clone git@github.com:negillett/alloc-context.git
+cd alloc-context
+python3.11 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+cp .env.example .env
+cp config/config.example.yaml config/config.yaml
+
+python -m alloccontext ingest --dry-run
+python -m alloccontext rollup --scope daily --stdout
+pytest
+```
+
+| Command | Purpose |
+|---------|---------|
+| `python -m alloccontext ingest` | Pull configured sources → SQLite |
+| `python -m alloccontext rollup --scope daily --stdout` | ContextBundle JSON (facts) |
+| `python -m alloccontext status` | Per-source ingest ages, snapshots, MCP `/health` |
+| `alloc-context mcp` | MCP server (stdio or HTTP) |
+
+HTTP MCP + x402: [mcp-http.md](docs/mcp-http.md). CLI entry point:
+`alloc-context` (same as `python -m alloccontext`).
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP (bridge default) |
+| [docs/user-config.md](docs/user-config.md) | Bridge `user.yaml` reference |
+| [docs/mcp.md](docs/mcp.md) | MCP tools and x402 |
+| [docs/agent-integration.md](docs/agent-integration.md) | Paid HTTP MCP + Bazaar for agents |
+| [docs/examples.md](docs/examples.md) | Sample tool JSON (redacted) |
+| [docs/context-bundle.md](docs/context-bundle.md) | ContextBundle schema |
+| [docs/USE.md](docs/USE.md) | Self-host vs hosted MCP (plain language) |
+| [docs/mcp-http.md](docs/mcp-http.md) | HTTP MCP + x402 setup |
+| [docs/mcp-discovery.md](docs/mcp-discovery.md) | Bazaar and agent discovery |
+| [docs/self-hosting.md](docs/self-hosting.md) | Optional Linux/systemd ingest + MCP |
+| [docs/local-dev.md](docs/local-dev.md) | Local internal MCP + dev ingest |
+| [docs/architecture.md](docs/architecture.md) | Pipeline and trust boundaries |
+| [docs/data-sources.md](docs/data-sources.md) | Ingest sources |
+| [docs/distribution.md](docs/distribution.md) | GitHub, PyPI, MCP Registry, directories |
+| [docs/publishing.md](docs/publishing.md) | Release workflow and version bumps |
+| [docs/security-ci.md](docs/security-ci.md) | CI coverage, Bandit, and pip-audit gates |
+
+## Contributing
+
+GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions.
+Unsolicited pull requests are not expected — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[Elastic License 2.0](LICENSE) — source-available, self-host friendly. See
+[docs/USE.md](docs/USE.md) for plain-language allowed uses.
+
+**Official hosted MCP:** `https://mcp.alloc-context.com/mcp`