solvent-agent 0.2.2__tar.gz → 0.3.0__tar.gz

{solvent_agent-0.2.2 → solvent_agent-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvent-agent
-Version: 0.2.2
+Version: 0.3.0
 Summary: A self-funding analyst agent: earns on Stripe, fulfils with NVIDIA Nemotron, spends within guardrails.
 License: MIT
 Project-URL: Homepage, https://github.com/ianalloway/solvent-agent
@@ -21,13 +21,19 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: stripe
 Requires-Dist: stripe>=9.0.0; extra == "stripe"
+Requires-Dist: urllib3>=2.8.0; extra == "stripe"
+Requires-Dist: certifi>=2026.10.19; extra == "stripe"
 Provides-Extra: serve
 Requires-Dist: fastapi>=0.110.0; extra == "serve"
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == "serve"
+Requires-Dist: anyio>=4.14.2; extra == "serve"
 Provides-Extra: qr
 Requires-Dist: qrcode[pil]>=7.0; extra == "qr"
+Requires-Dist: pillow>=13.0.0; python_version >= "3.11" and extra == "qr"
 Provides-Extra: telegram
 Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
+Requires-Dist: anyio>=4.14.2; extra == "telegram"
+Requires-Dist: certifi>=2026.10.19; extra == "telegram"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: ruff>=0.3; extra == "dev"
@@ -37,6 +43,10 @@ Requires-Dist: fastapi>=0.110.0; extra == "all"
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == "all"
 Requires-Dist: qrcode[pil]>=7.0; extra == "all"
 Requires-Dist: python-telegram-bot>=21.0; extra == "all"
+Requires-Dist: urllib3>=2.8.0; extra == "all"
+Requires-Dist: certifi>=2026.10.19; extra == "all"
+Requires-Dist: anyio>=4.14.2; extra == "all"
+Requires-Dist: pillow>=13.0.0; python_version >= "3.11" and extra == "all"
 Dynamic: license-file
 
 <div align="center">
@@ -47,6 +57,7 @@ Dynamic: license-file
 
 [![CI](https://github.com/ianalloway/solvent-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/ianalloway/solvent-agent/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/solvent-agent.svg)](https://pypi.org/project/solvent-agent/)
+[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-try%20in%20browser-yellow)](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![Zero dependencies](https://img.shields.io/badge/core%20deps-0-brightgreen)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -59,6 +70,11 @@ Dynamic: license-file
 
 <sub>Recorded from the real CLI with no API keys and no network access: the Stripe checkout links and Nemotron output are the built-in offline stubs, and the dollar figures are simulated.</sub>
 
+**[▶ Try it in your browser](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)**: the real package running in Pyodide, with no install and no keys.
+
+[![The SOLVENT Hugging Face Space: five jobs run, J3 declined with a $15 counter-offer, and a simulated P&L snapshot](docs/hf-space-demo.png)](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)
+
+<sub>All dollar figures, including the final cash balance, are simulated.</sub>
 </div>
 
 > **Demo by default.** With no keys set, `solvent` runs an **offline, zero-key simulation** of the whole loop. Dollar figures in the demo are illustrative, **not production revenue**. Stripe test-mode Payment Links and live NVIDIA Nemotron are opt-in; see [Make It Real](#-make-it-real).
@@ -196,7 +212,10 @@ A typical **offline demo** batch (illustrative numbers from the simulated run
    BOOK P&L  ──▶ treasury updated · dashboard refreshed
 ```
 
-Revenue is **always collected before cost is incurred**, and no payment can violate policy. The business is safe by construction and profitable by rule.
+The job pipeline checks payment before fulfilment and screens vendor payments
+against the configured spend policy. Quotes use estimated costs, so an accepted
+quote is a projected margin, not a guarantee of realized profit. The ledger and
+cost-calibration reports show how actual spending compares with that estimate.
 
 ---
 
@@ -218,6 +237,11 @@ Revenue is **always collected before cost is incurred**, and no payment can viol
 - **Offline-first** — without API keys the demo runs on deterministic stubs. Add `NVIDIA_API_KEY` + `STRIPE_API_KEY=sk_test_...` to unlock live inference and real Payment Links.
 - **Audit trail** — every `cs_...` checkout session ID and `pi_...` PaymentIntent ID is recorded on the ledger before fulfilment begins.
 
+Resource prices can be overridden in `.solvent/pricing_overrides.json`. Values
+are costs in cents and must be finite, non-negative numbers; `0` is valid for a
+free resource. Invalid entries (including negative values, booleans, `NaN`, and
+infinity) keep the built-in price. Valid entries in the same file still apply.
+
 ---
 
 ## 🎮 Running Modes
@@ -295,6 +319,8 @@ python3 -m solvent export --since 30d     # ledger/jobs/metrics/customers + peri
 python3 -m solvent products               # the price list, checked against current cost
 python3 -m solvent quality                # scores the quality gate gave shipped briefs
 python3 -m solvent review                 # approve/reject the jobs intake held for a human
+python3 -m solvent funnel --since 7d      # win rate: submitted → quoted → paid → delivered
+python3 -m solvent turnaround             # measured paid-to-delivered time, and the promise
 python3 -m solvent reconcile --since 7d   # Stripe ↔ ledger drift check
 python3 -m solvent finance                # income statement, unit economics, runway
 python3 -m solvent finance --json         # machine-readable report
@@ -376,6 +402,65 @@ directory, move them into this resolved directory before upgrading.
 rolling window is used, per-vendor exposure against its cap, and every spend
 the policy blocked.
 
+### Spending controls — per-job envelopes and human approval
+
+Two more rules sit on top of the daily, per-vendor and velocity limits. Both
+run inside the same deterministic guardrail check, before any Stripe call, and
+both fail closed.
+
+| Rule | Decision rule id | What happens |
+|---|---|---|
+| **Per-job budget envelope** | `job_budget` | Every job has a hard spend cap in integer cents (`job_budget_cents`, default 15000 = $150; `0` turns it off). Spend up to *exactly* the cap is allowed; anything that would go past it is refused with "job '…' budget exhausted". Refunds don't count against it. |
+| **Human-approval hook** | `approval_pending` / `approval_denied` | A spend *strictly above* `approval_threshold_cents` is not paid. It goes to a pluggable approver, which answers `"approved"`, `"denied"` or `"held"`. The default approver always holds. An approver that raises an error or returns anything else also holds. Approval cannot override a hard rule such as the job envelope. |
+
+Configure them in `.solvent/spend_policy.json`:
+
+```json
+{ "job_budget_cents": 8000, "approval_threshold_cents": 2500 }
+```
+
+or with the environment variables `SOLVENT_JOB_BUDGET_CENTS` and
+`SOLVENT_APPROVAL_THRESHOLD_CENTS`. Env vars can only **tighten** these
+settings: a lower budget or a lower threshold. An env value that would raise
+or disable a limit (for example `SOLVENT_JOB_BUDGET_CENTS=0`) is ignored.
+Loosening or disabling takes an explicit policy-file setting, and any override
+that loosens or disables a limit, or is ignored, is logged as a warning and
+shown in `solvent guardrails`. The approval hook is off unless a threshold is
+set.
+
+A spend evaluated without a job id is not exempt from the budget. All unscoped
+spends share one `unscoped` envelope under the same cap.
+
+Wire in your own approver (a Slack prompt, a ticket queue, a CLI confirm):
+
+```python
+from solvent.guardrails import ApprovalRequest, Guardrails
+
+def approver(req: ApprovalRequest) -> str:
+    return "approved" if req.vendor == "market-data-api" else "held"
+
+guard = Guardrails(treasury, approver=approver)
+```
+
+A held spend stops the job and emits a `spend_held` event, so nothing moves
+until a human decides.
+
+**How this relates to the card networks.** The pattern is close to what the
+networks describe publicly. Mastercard's
+[Agent Pay for Machines](https://www.mastercard.com/global/en/news-and-trends/press/2026/october/Mastercard-Agent-Pay-for-Machines-in-action.html)
+gives an agent "a job and a spending limit", and Mastercard's
+[agentic token framework](https://www.mastercard.com/us/en/news-and-trends/stories/2025/agentic-commerce-framework.html)
+carries transaction limits and validity windows. In the
+[Visa, BILL and Billtrust pilot](https://corporate.visa.com/en/sites/visa-perspectives/newsroom/visa-bill-billtrust-launch-pilot.html),
+the agent only pays invoices the buyer has already approved. Stripe's
+[Issuing for agents](https://docs.stripe.com/issuing/agents) offers per-card and
+per-cardholder
+[spending controls](https://docs.stripe.com/issuing/controls/spending-controls)
+and real-time authorization webhooks. Those controls run at the card or network
+layer. Solvent's run inside the agent, before it calls any payment API, so they
+work in simulation and with any payment backend. They complement network-level
+controls and don't replace them.
+
 ### Backlog — which job to work on next
 
 A queue is not a plan. When several jobs are open and both cash and the 24h
@@ -524,6 +609,102 @@ a single JSON document, over a period given as `7d`, `24h`, `2w`, `3m` or
 revenue and cost counted when the money moved — so the printed summary ties out
 against the rows it ships, with refunds separated from cost of sales.
 
+### How long it takes
+
+"When will I get it?" is the second question every customer asks, and the agent
+had no answer. Fulfilment seconds were recorded, but that is only the model's
+part — what the customer experiences is the wait from *paying* to *having the
+brief*, across the queue, the worker's poll, retries and delivery.
+
+That wait is already on the record (the ledger says when the money arrived, the
+event log says when the brief went out), so `solvent turnaround` measures it
+rather than estimating, and turns the distribution into something quotable: a
+promise at a chosen percentile, rounded up, never faster than a floor. The
+promise then appears on accepted quotes:
+
+```
+  Verdict              ACCEPT — accepted
+  Turnaround           within 5 minutes
+```
+
+It also retires an arbitrary threshold. `alerts.py` called a paid job "stuck"
+after two hours because two hours sounded reasonable; a shop that normally
+delivers in forty seconds should not wait two hours to notice, and one that
+takes a day should not cry wolf. With enough history, late is defined by the
+shop's own p95 — and only until then by the fixed hours.
+
+### Running it from Telegram
+
+Fifteen commands' worth of reporting lived in the CLI, which is where the
+operator is not. The gateway's slash commands now cover the business too —
+`/funnel`, `/customers`, `/capacity`, `/alerts`, `/products`, `/quality`,
+`/review`, `/costs` — each a short read over local state, no model call, no
+spend.
+
+The catch is who is asking. Any *paired* Telegram user reaches that handler,
+and a customer is not entitled to the agent's win rate or cash position, so
+these are operator-only:
+
+- the **dashboard** channel is the operator by construction — it sits behind
+  `SOLVENT_DASHBOARD_TOKEN`;
+- a Telegram id in `SOLVENT_OPERATOR_IDS` is the operator;
+- anyone else gets "That command is operator-only", and `/help` does not list
+  commands they cannot run.
+
+### The deliverable
+
+Every job has been billed `pdf-render-saas` since the first commit, and no PDF
+was ever produced — the agent was paying itself for a deliverable it did not
+deliver. It renders one now: markdown, HTML **and** PDF, written beside each
+other in `data/reports/`, linked from the delivery email and served from the
+same token-gated route as the brief itself (`&format=pdf`), so nothing new is
+exposed. With SMTP configured the PDF is attached to the email.
+
+The renderer is `solvent/pdf.py`, about 250 lines of stdlib: a PDF is a text
+container with a byte-offset table, so a single-font document needs no library,
+only exact xref offsets. Base-14 Helvetica means nothing is embedded and a
+brief weighs a couple of kilobytes. A render failure is caught and logged
+rather than raised — losing a brief the customer has paid for would be far
+worse than shipping it without the PDF.
+
+### Knowing the win rate
+
+**`solvent funnel`.** The treasury has always known the margin on the jobs it
+took; it never knew the win rate. Those are different businesses — a 90% margin
+on one job in ten is a worse shop than a 60% margin on eight, and nothing here
+could tell them apart.
+
+Every stage already leaves a trace, so the funnel is a read over data the agent
+keeps anyway: submitted → quoted → accepted → checkout → paid → delivered. What
+falls out at each step is the point, and the three failures want three
+different fixes:
+
+| Exit | What it means |
+|---|---|
+| `screened` | held before pricing — cost nothing |
+| `declined` | a customer who wanted to pay and was turned away by the margin gate |
+| `abandoned` | a customer who said yes at checkout and then did not pay |
+| `refunded` | paid, then refunded when fulfilment failed — the expensive loss |
+
+Lost pipeline is reported at the price the customer named, because that is the
+money that was on the table. Win rate is broken down by product and price band,
+and counter-offers are tracked separately, so "does the counter-offer actually
+convert?" finally has an answer.
+
+```
+  Submitted                 9  ████████████████████████ 100.0%
+  Accepted by the gate      6  ████████████████········ 66.7%
+  Paid                      5  █████████████··········· 55.6%
+
+  Gate acceptance      85.7%   ·  payment conversion 83.3%
+  Won $373.00  ·  left on the table $9,130.00
+  Counter-offers       1 made, 0 won (0.0%)
+```
+
+The same picture now has a **Commercial** panel in the HTML dashboard — win
+rate, customer book, brief quality and the throughput ceiling beside the P&L —
+so the business reads in one place instead of across six commands.
+
 ### Selling, not just quoting
 
 **`solvent products` — a price list.** A shop that cannot say what it charges
@@ -538,8 +719,29 @@ curl -X POST localhost:8787/jobs -d '{"topic": "...", "product": "deep-dive", ..
 
 The catalogue is priced against *current* costs — calibration included — so a
 list price that has quietly stopped clearing the margin floor shows up as a
-stale price rather than as a run of unprofitable work. The command exits
-non-zero when any product has gone stale, so cron can catch it.
+stale price rather than as a run of unprofitable work.
+
+Changing what the shop sells is a business decision, not a code change, so the
+built-in list is overridable in `.solvent/products.json` beside the spend and
+intake policies. Entries merge by slug — naming only a price keeps the built-in
+scope — `retire` drops a product, and `replace: true` makes the file the whole
+list:
+
+```json
+{
+  "products": [
+    { "slug": "express", "list_price_cents": 3500 },
+    { "slug": "retainer", "name": "Monthly retainer", "list_price_cents": 49900,
+      "est_tokens": 60000, "market_data_calls": 12, "web_search_calls": 40 }
+  ],
+  "retire": ["deep-dive"]
+}
+```
+
+A malformed entry is dropped rather than sold — a half-read product is a price
+nobody agreed to — and `solvent products --validate` reports it. The command
+exits non-zero when any product has gone stale *or* the file is broken, so cron
+catches either without reading the output.
 
 **`solvent quality` — a gate on the product, not just the margin.** Every other
 gate here asks whether the money is sound; this one asks whether the brief is.
@@ -595,6 +797,22 @@ With both keys set:
 - Optional: set `STRIPE_WEBHOOK_SECRET` and forward `checkout.session.completed` events via `StripeClient.process_webhook()`.
 - Optional: enable **Stripe Issuing** on your test account to provision capped single-use virtual debit cards for each vendor payment.
 
+### Local or OpenAI-compatible model (Ollama, LM Studio, vLLM)
+
+Briefs can be written by any OpenAI-compatible `/chat/completions` server instead of Nemotron. This is opt-in, uses only the standard library, and is ignored unless you set one of the variables below:
+
+```bash
+ollama pull llama3.2
+export SOLVENT_LLM_MODEL=llama3.2                       # base URL defaults to Ollama
+# export SOLVENT_LLM_BASE_URL=http://localhost:11434/v1  # or any OpenAI-compatible URL
+# export SOLVENT_LLM_API_KEY=...                         # optional; sent only as a Bearer header
+solvent --no-onboard
+```
+
+If the server is down, slow (`SOLVENT_LLM_TIMEOUT`, default 30s), or returns an error or malformed reply, SOLVENT logs a warning and falls back to the deterministic offline brief, so the job still completes. The API key is never logged or written to a brief.
+
+**API keys.** `SOLVENT_LLM_API_KEY` stays on your machine: it is read from the environment and sent only as a Bearer header to the configured `SOLVENT_LLM_BASE_URL`, never anywhere else. Redirects are refused rather than followed, so a 3xx can never forward the key to another host or downgrade it to `http://`; point the base URL at the final endpoint. Give each tool its own key with a spend cap, so one leaked or misbehaving key can only spend so much.
+
 ### Environment variables
 
 | Variable | Purpose |
@@ -612,6 +830,10 @@ With both keys set:
 | `SOLVENT_TELEGRAM_ALLOW_FROM` | Comma-separated Telegram user IDs for allowlist mode |
 | `SOLVENT_PORT` | Port for the `serve` API server (default `8787`) |
 | `SOLVENT_BASE_URL` | Base URL for hosted brief links and Stripe webhook callbacks |
+| `SOLVENT_LLM_BASE_URL` | Opt-in OpenAI-compatible endpoint for briefs (default when enabled: `http://localhost:11434/v1`, Ollama) |
+| `SOLVENT_LLM_MODEL` | Model name for that endpoint; setting it alone enables the backend (default `llama3.2`) |
+| `SOLVENT_LLM_API_KEY` | Optional Bearer key for the endpoint; never logged |
+| `SOLVENT_LLM_TIMEOUT` | Request timeout in seconds for that endpoint (default `30`) |
 | `NEMOTRON_MODEL` | Nemotron model override (default: `nvidia/llama-3.1-nemotron-ultra-253b-v1`) |
 | `SOLVENT_DELIVERY_SECRET` | HMAC token secret for `/briefs/{job_id}`; at least 32 characters, high entropy |
 | `SOLVENT_SKIP_ONBOARD` | Set to `1` to skip the first-run wizard |
@@ -694,9 +916,13 @@ solvent/
   products.py      the price list (`solvent products`)
   quality.py       deliverable quality gate (`solvent quality`)
   review.py        operator approval queue (`solvent review`)
+  funnel.py        order funnel and win rate (`solvent funnel`)
+  turnaround.py    measured delivery time (`solvent turnaround`)
+  ops.py           operator-only business commands on the chat surface
   stripe_client.py two-sided Stripe layer (earn + spend)
   nemotron.py      NVIDIA Nemotron client (+ offline stub)
   service.py       the product: an on-demand research brief
+  pdf.py           dependency-free PDF rendering of the brief
   jobs.py          sample inbound work
   dashboard.py     renders the treasury to HTML + JSON
   finance.py       income statement · unit economics · runway · forecast

{solvent_agent-0.2.2 → solvent_agent-0.3.0}/README.md

@@ -6,6 +6,7 @@
 
 [![CI](https://github.com/ianalloway/solvent-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/ianalloway/solvent-agent/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/solvent-agent.svg)](https://pypi.org/project/solvent-agent/)
+[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-try%20in%20browser-yellow)](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![Zero dependencies](https://img.shields.io/badge/core%20deps-0-brightgreen)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -18,6 +19,11 @@
 
 <sub>Recorded from the real CLI with no API keys and no network access: the Stripe checkout links and Nemotron output are the built-in offline stubs, and the dollar figures are simulated.</sub>
 
+**[▶ Try it in your browser](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)**: the real package running in Pyodide, with no install and no keys.
+
+[![The SOLVENT Hugging Face Space: five jobs run, J3 declined with a $15 counter-offer, and a simulated P&L snapshot](docs/hf-space-demo.png)](https://huggingface.co/spaces/ianalloway/solvent-agent-demo)
+
+<sub>All dollar figures, including the final cash balance, are simulated.</sub>
 </div>
 
 > **Demo by default.** With no keys set, `solvent` runs an **offline, zero-key simulation** of the whole loop. Dollar figures in the demo are illustrative, **not production revenue**. Stripe test-mode Payment Links and live NVIDIA Nemotron are opt-in; see [Make It Real](#-make-it-real).
@@ -155,7 +161,10 @@ A typical **offline demo** batch (illustrative numbers from the simulated run
    BOOK P&L  ──▶ treasury updated · dashboard refreshed
 ```
 
-Revenue is **always collected before cost is incurred**, and no payment can violate policy. The business is safe by construction and profitable by rule.
+The job pipeline checks payment before fulfilment and screens vendor payments
+against the configured spend policy. Quotes use estimated costs, so an accepted
+quote is a projected margin, not a guarantee of realized profit. The ledger and
+cost-calibration reports show how actual spending compares with that estimate.
 
 ---
 
@@ -177,6 +186,11 @@ Revenue is **always collected before cost is incurred**, and no payment can viol
 - **Offline-first** — without API keys the demo runs on deterministic stubs. Add `NVIDIA_API_KEY` + `STRIPE_API_KEY=sk_test_...` to unlock live inference and real Payment Links.
 - **Audit trail** — every `cs_...` checkout session ID and `pi_...` PaymentIntent ID is recorded on the ledger before fulfilment begins.
 
+Resource prices can be overridden in `.solvent/pricing_overrides.json`. Values
+are costs in cents and must be finite, non-negative numbers; `0` is valid for a
+free resource. Invalid entries (including negative values, booleans, `NaN`, and
+infinity) keep the built-in price. Valid entries in the same file still apply.
+
 ---
 
 ## 🎮 Running Modes
@@ -254,6 +268,8 @@ python3 -m solvent export --since 30d     # ledger/jobs/metrics/customers + peri
 python3 -m solvent products               # the price list, checked against current cost
 python3 -m solvent quality                # scores the quality gate gave shipped briefs
 python3 -m solvent review                 # approve/reject the jobs intake held for a human
+python3 -m solvent funnel --since 7d      # win rate: submitted → quoted → paid → delivered
+python3 -m solvent turnaround             # measured paid-to-delivered time, and the promise
 python3 -m solvent reconcile --since 7d   # Stripe ↔ ledger drift check
 python3 -m solvent finance                # income statement, unit economics, runway
 python3 -m solvent finance --json         # machine-readable report
@@ -335,6 +351,65 @@ directory, move them into this resolved directory before upgrading.
 rolling window is used, per-vendor exposure against its cap, and every spend
 the policy blocked.
 
+### Spending controls — per-job envelopes and human approval
+
+Two more rules sit on top of the daily, per-vendor and velocity limits. Both
+run inside the same deterministic guardrail check, before any Stripe call, and
+both fail closed.
+
+| Rule | Decision rule id | What happens |
+|---|---|---|
+| **Per-job budget envelope** | `job_budget` | Every job has a hard spend cap in integer cents (`job_budget_cents`, default 15000 = $150; `0` turns it off). Spend up to *exactly* the cap is allowed; anything that would go past it is refused with "job '…' budget exhausted". Refunds don't count against it. |
+| **Human-approval hook** | `approval_pending` / `approval_denied` | A spend *strictly above* `approval_threshold_cents` is not paid. It goes to a pluggable approver, which answers `"approved"`, `"denied"` or `"held"`. The default approver always holds. An approver that raises an error or returns anything else also holds. Approval cannot override a hard rule such as the job envelope. |
+
+Configure them in `.solvent/spend_policy.json`:
+
+```json
+{ "job_budget_cents": 8000, "approval_threshold_cents": 2500 }
+```
+
+or with the environment variables `SOLVENT_JOB_BUDGET_CENTS` and
+`SOLVENT_APPROVAL_THRESHOLD_CENTS`. Env vars can only **tighten** these
+settings: a lower budget or a lower threshold. An env value that would raise
+or disable a limit (for example `SOLVENT_JOB_BUDGET_CENTS=0`) is ignored.
+Loosening or disabling takes an explicit policy-file setting, and any override
+that loosens or disables a limit, or is ignored, is logged as a warning and
+shown in `solvent guardrails`. The approval hook is off unless a threshold is
+set.
+
+A spend evaluated without a job id is not exempt from the budget. All unscoped
+spends share one `unscoped` envelope under the same cap.
+
+Wire in your own approver (a Slack prompt, a ticket queue, a CLI confirm):
+
+```python
+from solvent.guardrails import ApprovalRequest, Guardrails
+
+def approver(req: ApprovalRequest) -> str:
+    return "approved" if req.vendor == "market-data-api" else "held"
+
+guard = Guardrails(treasury, approver=approver)
+```
+
+A held spend stops the job and emits a `spend_held` event, so nothing moves
+until a human decides.
+
+**How this relates to the card networks.** The pattern is close to what the
+networks describe publicly. Mastercard's
+[Agent Pay for Machines](https://www.mastercard.com/global/en/news-and-trends/press/2026/october/Mastercard-Agent-Pay-for-Machines-in-action.html)
+gives an agent "a job and a spending limit", and Mastercard's
+[agentic token framework](https://www.mastercard.com/us/en/news-and-trends/stories/2025/agentic-commerce-framework.html)
+carries transaction limits and validity windows. In the
+[Visa, BILL and Billtrust pilot](https://corporate.visa.com/en/sites/visa-perspectives/newsroom/visa-bill-billtrust-launch-pilot.html),
+the agent only pays invoices the buyer has already approved. Stripe's
+[Issuing for agents](https://docs.stripe.com/issuing/agents) offers per-card and
+per-cardholder
+[spending controls](https://docs.stripe.com/issuing/controls/spending-controls)
+and real-time authorization webhooks. Those controls run at the card or network
+layer. Solvent's run inside the agent, before it calls any payment API, so they
+work in simulation and with any payment backend. They complement network-level
+controls and don't replace them.
+
 ### Backlog — which job to work on next
 
 A queue is not a plan. When several jobs are open and both cash and the 24h
@@ -483,6 +558,102 @@ a single JSON document, over a period given as `7d`, `24h`, `2w`, `3m` or
 revenue and cost counted when the money moved — so the printed summary ties out
 against the rows it ships, with refunds separated from cost of sales.
 
+### How long it takes
+
+"When will I get it?" is the second question every customer asks, and the agent
+had no answer. Fulfilment seconds were recorded, but that is only the model's
+part — what the customer experiences is the wait from *paying* to *having the
+brief*, across the queue, the worker's poll, retries and delivery.
+
+That wait is already on the record (the ledger says when the money arrived, the
+event log says when the brief went out), so `solvent turnaround` measures it
+rather than estimating, and turns the distribution into something quotable: a
+promise at a chosen percentile, rounded up, never faster than a floor. The
+promise then appears on accepted quotes:
+
+```
+  Verdict              ACCEPT — accepted
+  Turnaround           within 5 minutes
+```
+
+It also retires an arbitrary threshold. `alerts.py` called a paid job "stuck"
+after two hours because two hours sounded reasonable; a shop that normally
+delivers in forty seconds should not wait two hours to notice, and one that
+takes a day should not cry wolf. With enough history, late is defined by the
+shop's own p95 — and only until then by the fixed hours.
+
+### Running it from Telegram
+
+Fifteen commands' worth of reporting lived in the CLI, which is where the
+operator is not. The gateway's slash commands now cover the business too —
+`/funnel`, `/customers`, `/capacity`, `/alerts`, `/products`, `/quality`,
+`/review`, `/costs` — each a short read over local state, no model call, no
+spend.
+
+The catch is who is asking. Any *paired* Telegram user reaches that handler,
+and a customer is not entitled to the agent's win rate or cash position, so
+these are operator-only:
+
+- the **dashboard** channel is the operator by construction — it sits behind
+  `SOLVENT_DASHBOARD_TOKEN`;
+- a Telegram id in `SOLVENT_OPERATOR_IDS` is the operator;
+- anyone else gets "That command is operator-only", and `/help` does not list
+  commands they cannot run.
+
+### The deliverable
+
+Every job has been billed `pdf-render-saas` since the first commit, and no PDF
+was ever produced — the agent was paying itself for a deliverable it did not
+deliver. It renders one now: markdown, HTML **and** PDF, written beside each
+other in `data/reports/`, linked from the delivery email and served from the
+same token-gated route as the brief itself (`&format=pdf`), so nothing new is
+exposed. With SMTP configured the PDF is attached to the email.
+
+The renderer is `solvent/pdf.py`, about 250 lines of stdlib: a PDF is a text
+container with a byte-offset table, so a single-font document needs no library,
+only exact xref offsets. Base-14 Helvetica means nothing is embedded and a
+brief weighs a couple of kilobytes. A render failure is caught and logged
+rather than raised — losing a brief the customer has paid for would be far
+worse than shipping it without the PDF.
+
+### Knowing the win rate
+
+**`solvent funnel`.** The treasury has always known the margin on the jobs it
+took; it never knew the win rate. Those are different businesses — a 90% margin
+on one job in ten is a worse shop than a 60% margin on eight, and nothing here
+could tell them apart.
+
+Every stage already leaves a trace, so the funnel is a read over data the agent
+keeps anyway: submitted → quoted → accepted → checkout → paid → delivered. What
+falls out at each step is the point, and the three failures want three
+different fixes:
+
+| Exit | What it means |
+|---|---|
+| `screened` | held before pricing — cost nothing |
+| `declined` | a customer who wanted to pay and was turned away by the margin gate |
+| `abandoned` | a customer who said yes at checkout and then did not pay |
+| `refunded` | paid, then refunded when fulfilment failed — the expensive loss |
+
+Lost pipeline is reported at the price the customer named, because that is the
+money that was on the table. Win rate is broken down by product and price band,
+and counter-offers are tracked separately, so "does the counter-offer actually
+convert?" finally has an answer.
+
+```
+  Submitted                 9  ████████████████████████ 100.0%
+  Accepted by the gate      6  ████████████████········ 66.7%
+  Paid                      5  █████████████··········· 55.6%
+
+  Gate acceptance      85.7%   ·  payment conversion 83.3%
+  Won $373.00  ·  left on the table $9,130.00
+  Counter-offers       1 made, 0 won (0.0%)
+```
+
+The same picture now has a **Commercial** panel in the HTML dashboard — win
+rate, customer book, brief quality and the throughput ceiling beside the P&L —
+so the business reads in one place instead of across six commands.
+
 ### Selling, not just quoting
 
 **`solvent products` — a price list.** A shop that cannot say what it charges
@@ -497,8 +668,29 @@ curl -X POST localhost:8787/jobs -d '{"topic": "...", "product": "deep-dive", ..
 
 The catalogue is priced against *current* costs — calibration included — so a
 list price that has quietly stopped clearing the margin floor shows up as a
-stale price rather than as a run of unprofitable work. The command exits
-non-zero when any product has gone stale, so cron can catch it.
+stale price rather than as a run of unprofitable work.
+
+Changing what the shop sells is a business decision, not a code change, so the
+built-in list is overridable in `.solvent/products.json` beside the spend and
+intake policies. Entries merge by slug — naming only a price keeps the built-in
+scope — `retire` drops a product, and `replace: true` makes the file the whole
+list:
+
+```json
+{
+  "products": [
+    { "slug": "express", "list_price_cents": 3500 },
+    { "slug": "retainer", "name": "Monthly retainer", "list_price_cents": 49900,
+      "est_tokens": 60000, "market_data_calls": 12, "web_search_calls": 40 }
+  ],
+  "retire": ["deep-dive"]
+}
+```
+
+A malformed entry is dropped rather than sold — a half-read product is a price
+nobody agreed to — and `solvent products --validate` reports it. The command
+exits non-zero when any product has gone stale *or* the file is broken, so cron
+catches either without reading the output.
 
 **`solvent quality` — a gate on the product, not just the margin.** Every other
 gate here asks whether the money is sound; this one asks whether the brief is.
@@ -554,6 +746,22 @@ With both keys set:
 - Optional: set `STRIPE_WEBHOOK_SECRET` and forward `checkout.session.completed` events via `StripeClient.process_webhook()`.
 - Optional: enable **Stripe Issuing** on your test account to provision capped single-use virtual debit cards for each vendor payment.
 
+### Local or OpenAI-compatible model (Ollama, LM Studio, vLLM)
+
+Briefs can be written by any OpenAI-compatible `/chat/completions` server instead of Nemotron. This is opt-in, uses only the standard library, and is ignored unless you set one of the variables below:
+
+```bash
+ollama pull llama3.2
+export SOLVENT_LLM_MODEL=llama3.2                       # base URL defaults to Ollama
+# export SOLVENT_LLM_BASE_URL=http://localhost:11434/v1  # or any OpenAI-compatible URL
+# export SOLVENT_LLM_API_KEY=...                         # optional; sent only as a Bearer header
+solvent --no-onboard
+```
+
+If the server is down, slow (`SOLVENT_LLM_TIMEOUT`, default 30s), or returns an error or malformed reply, SOLVENT logs a warning and falls back to the deterministic offline brief, so the job still completes. The API key is never logged or written to a brief.
+
+**API keys.** `SOLVENT_LLM_API_KEY` stays on your machine: it is read from the environment and sent only as a Bearer header to the configured `SOLVENT_LLM_BASE_URL`, never anywhere else. Redirects are refused rather than followed, so a 3xx can never forward the key to another host or downgrade it to `http://`; point the base URL at the final endpoint. Give each tool its own key with a spend cap, so one leaked or misbehaving key can only spend so much.
+
 ### Environment variables
 
 | Variable | Purpose |
@@ -571,6 +779,10 @@ With both keys set:
 | `SOLVENT_TELEGRAM_ALLOW_FROM` | Comma-separated Telegram user IDs for allowlist mode |
 | `SOLVENT_PORT` | Port for the `serve` API server (default `8787`) |
 | `SOLVENT_BASE_URL` | Base URL for hosted brief links and Stripe webhook callbacks |
+| `SOLVENT_LLM_BASE_URL` | Opt-in OpenAI-compatible endpoint for briefs (default when enabled: `http://localhost:11434/v1`, Ollama) |
+| `SOLVENT_LLM_MODEL` | Model name for that endpoint; setting it alone enables the backend (default `llama3.2`) |
+| `SOLVENT_LLM_API_KEY` | Optional Bearer key for the endpoint; never logged |
+| `SOLVENT_LLM_TIMEOUT` | Request timeout in seconds for that endpoint (default `30`) |
 | `NEMOTRON_MODEL` | Nemotron model override (default: `nvidia/llama-3.1-nemotron-ultra-253b-v1`) |
 | `SOLVENT_DELIVERY_SECRET` | HMAC token secret for `/briefs/{job_id}`; at least 32 characters, high entropy |
 | `SOLVENT_SKIP_ONBOARD` | Set to `1` to skip the first-run wizard |
@@ -653,9 +865,13 @@ solvent/
   products.py      the price list (`solvent products`)
   quality.py       deliverable quality gate (`solvent quality`)
   review.py        operator approval queue (`solvent review`)
+  funnel.py        order funnel and win rate (`solvent funnel`)
+  turnaround.py    measured delivery time (`solvent turnaround`)
+  ops.py           operator-only business commands on the chat surface
   stripe_client.py two-sided Stripe layer (earn + spend)
   nemotron.py      NVIDIA Nemotron client (+ offline stub)
   service.py       the product: an on-demand research brief
+  pdf.py           dependency-free PDF rendering of the brief
   jobs.py          sample inbound work
   dashboard.py     renders the treasury to HTML + JSON
   finance.py       income statement · unit economics · runway · forecast

{solvent_agent-0.2.2 → solvent_agent-0.3.0}/pyproject.toml

@@ -24,10 +24,10 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-stripe = ["stripe>=9.0.0"]
-serve = ["fastapi>=0.110.0", "uvicorn[standard]>=0.27.0"]
-qr = ["qrcode[pil]>=7.0"]
-telegram = ["python-telegram-bot>=21.0"]
+stripe = ["stripe>=9.0.0", "urllib3>=2.8.0", "certifi>=2026.10.19"]
+serve = ["fastapi>=0.110.0", "uvicorn[standard]>=0.27.0", "anyio>=4.14.2"]
+qr = ["qrcode[pil]>=7.0", "pillow>=13.0.0; python_version >= '3.11'"]
+telegram = ["python-telegram-bot>=21.0", "anyio>=4.14.2", "certifi>=2026.10.19"]
 dev = ["pytest>=7.0.0", "ruff>=0.3"]
 all = [
     "stripe>=9.0.0",
@@ -35,6 +35,11 @@ all = [
     "uvicorn[standard]>=0.27.0",
     "qrcode[pil]>=7.0",
     "python-telegram-bot>=21.0",
+    # Security floors for transitive deps (verified GHSAs, Oct 2026). See constraints.txt.
+    "urllib3>=2.8.0",
+    "certifi>=2026.10.19",
+    "anyio>=4.14.2",
+    "pillow>=13.0.0; python_version >= '3.11'",
 ]
 
 [project.scripts]