nexusquant-cli 0.2.0__tar.gz → 0.3.0__tar.gz

nexusquant_cli-0.3.0/CLAUDE.md

@@ -0,0 +1,59 @@
+# nexusquant-cli
+
+Python CLI for NexusQuant users, strategy providers and admins. Cognito PKCE browser login, token storage/refresh, and wrappers over the nexus-service REST API.
+
+Two entry points, one login (credentials shared with nexusquant-sdk under `platformdirs/nexusquant-sdk/credentials.json`):
+
+- `nexus-cli` (`nexusquant_cli/nexus.py`) — `nexus-cli <role> <verb> <resource>`; roles `investor` / `provider` / `admin`, plus `auth`.
+- `nexusquant` (`nexusquant_cli/main.py`) — legacy flat provider layout. Keep it working: scheduled tasks and the nexus-admin webhook-adapter skill call it, and `webhook_admin.py` imports `nexusquant_cli.api_client`, `config` and `auth_pkce.ensure_fresh_id_token` directly.
+
+## Code structure
+
+```
+nexusquant_cli/
+  nexus.py          # nexus-cli entry (role groups)
+  main.py           # legacy nexusquant entry
+  roles/            # auth / investor / provider / admin — verb-first sub-apps
+                    #   provider.py mounts the functions from commands/ rather than copying them
+  commands/         # legacy command bodies (auth, strategy, policy) + _util (fail / JSON helpers)
+  api_client.py     # HTTP wrapper; ApiError; retries once on stale-Wall-Pro 403
+  identity.py       # decode local ID token for whoami / 403 hints (display only, never gates)
+  auth_pkce.py      # Cognito PKCE flow
+  config.py         # endpoints, credential path
+docs/investor-operations.md  # investor API surface survey + phase-2 roadmap
+tests/              # pytest, httpx.MockTransport — no network
+```
+
+Tests: `pip install -e '.[dev]' && python -m pytest -q tests`.
+
+Investor commands deliberately exclude anything that arms auto-trading, changes sizing, or touches broker secrets — see docs/investor-operations.md before adding those.
+
+## Install
+
+```bash
+# Development (editable)
+pip install -e .
+
+# From PyPI
+pip install nexusquant-cli
+```
+
+## Usage
+
+See README.md.
+
+## Deploy / publish
+
+```bash
+# Build distribution
+python -m build
+
+# Publish to PyPI
+twine upload dist/*
+```
+
+## Configuration
+
+API base URL is set in `nexusquant_cli/config.py`. Change `API_BASE_URL` to point at a different environment (staging vs production).
+
+Provider commands need `custom:userType=strategyProvider` or admin; admin commands need admin (or the `admin` Cognito group). User commands work for any login; some need Wall Pro.

nexusquant_cli-0.3.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.5
+Name: nexusquant-cli
+Version: 0.3.0
+Summary: NexusQuant CLI for users, strategy providers and admins
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: nexusquant-sdk>=0.2
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nexusquant-cli
+
+Command line tool for NexusQuant investors, strategy providers and admins.
+
+It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus APIs. Two entry points share one login:
+
+- **`nexus-cli`** — role-first grammar, `nexus-cli <role> <verb> <resource> [args]`. Use this.
+- `nexusquant` — the original flat provider layout (`nexusquant strategy|policy …`), kept unchanged for existing scripts. Everything below the `nexus-cli` section documents it.
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+```bash
+pip install nexusquant-cli
+```
+
+## nexus-cli
+
+```bash
+nexus-cli auth login          # browser login; one login covers every role
+nexus-cli auth whoami         # account, userType, Wall Pro tier, usable roles
+```
+
+The role is not picked at login — it is the account's `custom:userType` (or the `admin` Cognito group), and the server checks it on every call. `whoami` reads it from the local token; on a 403 the CLI prints which account type is logged in.
+
+Every read takes `--json` for scripting; the default output is a table.
+
+### investor — any logged-in account
+
+| Command | What it does |
+|---|---|
+| `investor list strategies [--subscribed]` | Marketplace, with backtest summary and a flag for strategies whose sizing reads your holdings |
+| `investor read strategy <id>` | Detail + 30 most recent signals |
+| `investor read backtest <id>` | Backtest stats, rolling returns, per-ticker attribution, return since you added it |
+| `investor subscribe strategy <id>...` | Add to My Strategies (Wall Pro). **Does not start auto-trading** |
+| `investor unsubscribe strategy <id> [-y]` | Remove from My Strategies; asks first, and warns if it is listening (this stops auto-trading) |
+| `investor list subscriptions` | My Strategies: listening on/off, config saved, broker |
+| `investor read config <id>` | Your personal config, effective config, and the schema of what you can set |
+| `investor list signals [--strategy-id --status --direction --limit --offset]` | Signals that reached you, with your own broker result for each |
+| `investor read stats` | Signal counts and broker success rate |
+| `investor read profile` / `investor read settings` | Account; daily-report setting |
+| `investor update settings --daily-report/--no-daily-report` | Toggle the daily report email |
+| `investor read container` | Trading environment state, broker login, selected account |
+| `investor list brokers` | Supported brokers and their login fields |
+| `investor list activity` | Your own activity log |
+
+#### Nexus AI agent — permissions and logs
+
+Nexus AI is the agent you chat with in the web app. Commands for the agent are under `investor`, and you can only **narrow** what it may do. The ceiling comes from your profile and is enforced on the agent host.
+
+```bash
+nexus-cli investor read agent-access                       # enabled?, profile, tools, extra denied tools
+nexus-cli investor update agent-access --profile readonly  # investor | readonly (admins: operator) | default
+nexus-cli investor update agent-access --deny-tool Write --deny-tool Edit
+nexus-cli investor update agent-access --clear-deny
+nexus-cli investor list agent-sessions                     # past conversations: title, turns, tool calls, denials, cost
+nexus-cli investor read agent-session ws-…                  # the full conversation, as it happened
+nexus-cli investor delete agent-session ws-…                # remove it from your history (soft delete)
+nexus-cli investor list agent-logs --denied                # every refused tool call
+nexus-cli investor list agent-logs --session ws-… --event tool_executed
+```
+
+| Profile | Tools | Files |
+|---|---|---|
+| `investor` | Read, Glob, Grep, Write, Edit, MultiEdit, TodoWrite, WebSearch. No shell, no sub-agents, no WebFetch | Only your own workspace |
+| `readonly` | `investor` without the write tools | Only your own workspace |
+| `operator` (admins only) | Everything | The whole agent workspace |
+
+- Conversations are kept permanently so you can read your history. Deleting one hides it from you; the platform keeps a copy, and admins can still see it.
+- Audit entries (the per-tool-call log) are kept for 90 days.
+- Changes apply to sessions opened afterwards.
+- Every tool call is logged: which tool, a summary of its input, and whether it was auto-allowed, approved by you, or refused. Refusals record who refused it: the profile, you, or a timeout.
+- Each turn also logs its cost.
+
+Not in the CLI yet, on purpose: switching listening on (arms auto-trading), editing sizing config, broker connect, container start/stop/reset, and webhook strategies. They place real orders or carry broker secrets and need their own confirmation / secret-handling design — see `docs/investor-operations.md`.
+
+### provider — `custom:userType=strategyProvider` or admin
+
+| Command | Same as legacy |
+|---|---|
+| `provider create strategy -i ID -n NAME [--schema-file …]` | `nexusquant strategy create` |
+| `provider list strategies` | `nexusquant strategy list` |
+| `provider list signals <id> [--limit --offset --status --direction]` | `nexusquant strategy signal <id> --history` |
+| `provider send signal <id> --ticker … --direction … --price … --quantity …` / `--signals-file` | `nexusquant strategy signal <id> --ticker …` |
+| `provider list subscribers <id>` | `nexusquant strategy sub config <id>` |
+| `provider list features [--scope --json]` | `nexusquant policy features` |
+| `provider publish policy --strategy-id … --ticker … --file …` | `nexusquant policy publish` |
+| `provider list policies <id>` | `nexusquant policy list` |
+| `provider update policy --policy-id … --mode off` | `nexusquant policy set-mode` |
+| `provider send policy-signal …` | `nexusquant policy send-signal` |
+
+Options are identical to the legacy commands documented below. One difference: `provider send signal` with no send fields is an error, where the legacy `strategy signal` silently listed history.
+
+### admin — `custom:userType=admin`
+
+```bash
+nexus-cli admin list reviews [--status all] [--verbose]
+nexus-cli admin review strategy <id> --action approve|reject|suspend [--note …]
+```
+
+```bash
+nexus-cli admin list agent-access                       # who besides admins may use Nexus AI
+nexus-cli admin grant agent-access --email someone@x.com
+nexus-cli admin revoke agent-access --email someone@x.com
+nexus-cli admin list agent-sessions [--email … | --user-id …] [--include-deleted]
+nexus-cli admin read agent-session ws-…                  # any user's conversation; each read goes into your admin activity log
+nexus-cli admin list agent-logs --email someone@x.com --denied
+```
+
+How grant and revoke take effect:
+- Granting adds the user to the `NEXUS_AI_USERS` flag. Non-admins can only connect once the backend's `NEXUS_AI_BRIDGE_POLICY` is also on.
+- Revoking refuses new connections within about 30 seconds. A session that is already open closes at its next token renewal; the web app renews every 20 minutes.
+
+Agent ops (weekly analysis uploads, S3 reads, Discord KB, notify) stay in `nexus-agent` (nexus-agent-cli) for now.
+
+## Legacy `nexusquant` commands
+
+### Login
+
+```bash
+nexusquant auth
+nexusquant auth --status
+nexusquant auth --refresh
+nexusquant auth --logout
+```
+
+Tokens are stored in the current OS user's config directory, for example `~/Library/Application Support/nexusquant-cli/credentials.json` on macOS. The file is written with `0600` permissions when supported.
+
+## Strategy Commands
+
+Create or update a strategy:
+
+```bash
+nexusquant strategy create \
+  --strategy-id my_alpha_001 \
+  --name "My Alpha" \
+  --schema-file schema.json \
+  --output-unit SHARE_COUNT
+```
+
+List strategies registered by the current provider. Admin users see all strategies:
+
+```bash
+nexusquant strategy list
+```
+
+List signal history for one strategy:
+
+```bash
+nexusquant strategy signal my_alpha_001 --history --limit 20
+```
+
+Send a single signal:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --ticker AAPL \
+  --direction buy \
+  --price 150.25 \
+  --quantity 100 \
+  --order-type MARKET
+```
+
+`--order-type` is a signal-level setting: `MARKET` or `LIMIT` (limit uses `--price`). Legacy `NORMAL` is accepted by the CLI as an alias for `LIMIT`. If omitted, the API defaults to `MARKET`.
+
+Send a multi-route `signals` map:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --signals-file signals.json
+```
+
+Get non-PII subscriber config for a strategy:
+
+```bash
+nexusquant strategy sub config my_alpha_001
+```
+
+## Policy Commands
+
+A SizingPolicy replaces the fixed `--quantity` on a signal with a **formula** that
+decides the order quantity — and optionally a limit price — at order time. You
+publish the formula once; each signal then carries only the parameter values it
+needs. Values that depend on the individual subscriber's account are never sent by
+you: they are bound inside that user's own container when the order is placed.
+
+Requires `custom:userType=strategyProvider` or `admin`, the same as the strategy
+commands.
+
+### See which names a formula may use
+
+The server registry is the authority — a name outside it cannot be published. Run
+this before writing a formula:
+
+```bash
+nexusquant policy features
+nexusquant policy features --scope shared    # names you send with each signal
+nexusquant policy features --scope account   # names bound in the user's container
+nexusquant policy features --json            # raw output for scripting
+```
+
+Account-scoped names carry a "suppliable" flag: a name that exists but that the
+container cannot currently supply will pass your editor and fail at publish.
+
+### Publish a formula
+
+```bash
+nexusquant policy publish --strategy-id my_alpha --ticker TQQQ --file tqqq.json
+nexusquant policy publish --strategy-id my_alpha --ticker TQQQ --file tqqq.json --profile normal
+```
+
+`--file` holds the two things a policy is made of — the formulas keyed by output
+slot, and the names you promise to supply with every signal:
+
+```json
+{
+  "expr": {
+    "f_depth":       "exp(-k_depth * depth / 10)",
+    "buy.quantity":  "target_shares * f_depth * clamp(1 - pos_ratio, 0, 1)",
+    "buy.price":     "ref_price * (1 - slip)",
+    "sell.quantity": "held_shares * exit_frac"
+  },
+  "params": ["target_shares", "k_depth", "depth", "ref_price", "slip", "exit_frac"]
+}
+```
+
+Output slots — the container picks the one matching the signal's direction:
+
+| Slot | What the formula yields |
+|---|---|
+| `buy.quantity` / `sell.quantity` | **Share count** (floored) |
+| `buy.price` / `sell.price` | **Limit price** — supplied ⇒ limit order, omitted ⇒ market order |
+
+Intermediate names (`f_depth`) are fine, but an `expr` must define at least one
+output slot, and an intermediate name may not contain a dot. `--ticker` is separate
+from the file because it is not part of the artifact: the same formula pointed at
+another symbol is the same formula.
+
+⚠️ **`publish` IS the go-live action.** There is no shadow or canary step, and the
+previous version on the same slot is deactivated. `--profile` defaults to `normal`.
+
+Before sending anything, the CLI fetches the registry and checks locally that every
+free name in your formula has someone to supply it — forgetting to list a name in
+`params` is the most common mistake. `--skip-name-check` disables that fetch, and
+then local success does not imply the server will accept.
+
+### List and stop
+
+```bash
+nexusquant policy list my_alpha
+nexusquant policy list my_alpha --ticker TQQQ --mode active   # --mode active / off
+
+# Emergency stop for a live version — not a promotion step, since publish already went live
+nexusquant policy set-mode --policy-id 'TQQQ/normal/…/abc123' --mode off
+nexusquant policy set-mode --policy-id 'TQQQ/normal/…/abc123' --mode active
+```
+
+### Send a signal against a policy
+
+Every declared parameter must be present, or the signal is rejected:
+
+```bash
+nexusquant policy send-signal \
+  --strategy-id my_alpha --ticker TQQQ --price 51.2 --direction buy \
+  -p target_shares=10 -p k_depth=0.5 -p depth=3 \
+  -p ref_price=51.2 -p slip=0.002 -p exit_frac=0.25
+
+# Or pass all parameter values as a JSON object
+nexusquant policy send-signal --strategy-id my_alpha --ticker TQQQ \
+  --price 51.2 --direction buy --params-file params.json
+
+# Validate and print the payload without sending it
+nexusquant policy send-signal ... --dry-run
+```
+
+| Flag | Meaning |
+|---|---|
+| `--param` / `-p` | One parameter value, `name=value`; repeat per declared name |
+| `--params-file` | A JSON object with all parameter values instead |
+| `--policy-id` | Defaults to the active policy on this `(strategy, ticker)` |
+| `--quantity` | Used when the formula has no slot for this direction |
+| `--order-type` | `MARKET` / `LIMIT` |
+| `--strategy-name` | Defaults to the strategy id |
+| `--no-fetch` | Skip fetching the policy — see below |
+| `--dry-run` | Validate and print the payload, send nothing |
+
+By default the CLI fetches the active policy first and uses it to validate and
+coerce your values. Three checks, each mirroring the server:
+
+| Situation | Result | Why not something else |
+|---|---|---|
+| A declared parameter is missing | Error | No defaults — a default turns "unknown" into "known" |
+| A name you did not declare | Error | The formula cannot reference it; extra names mean the two sides disagree |
+| An account-state name (`pos_ratio`, `held_shares`, …) | Error | Its value never leaves the execution plane |
+
+`--no-fetch` skips the fetch, and then **only the account-state rule is checked** —
+the rest is unknowable locally, so it is not pretended.
+
+⚠️ **The server is always the authority.** Passing local validation does not mean
+the server will accept — policy state and review status live there. This layer only
+moves the obvious mistakes onto your machine, where you can see which field is
+wrong instead of guessing from a rejection.
+
+⚠️ **There is no publish-time bound on order size.** Parameters are names only,
+with no declared domain, so nothing proves at publish time that a formula stays
+under a limit. How large an order it can place is clamped at order time by the
+subscriber's own `max_order_cash_usd`. Keep your formulas in a sane range yourself.
+
+## JSON Inputs
+
+`--schema-file` must contain the `strategy_schema` object accepted by `nexus-service`, for example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "window": {
+      "type": "integer",
+      "default": 14,
+      "title": "Window",
+      "source": "user"
+    }
+  },
+  "required": []
+}
+```
+
+`--signals-file` must contain a JSON object whose keys are `default` or user ids:
+
+```json
+{
+  "default": {
+    "ticker": "AAPL",
+    "time": "2026-04-26T19:30:00Z",
+    "price": 150.25,
+    "direction": "buy",
+    "order_type": "LIMIT",
+    "quantity": 100,
+    "metadata": {}
+  }
+}
+```
+
+## Environment Overrides
+
+Normal use does not require configuration. For staging or local development:
+
+| Variable                       | Meaning                                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------------- |
+| `NEXUSQUANT_API_ENDPOINT`      | API endpoint host, default `https://api.nexusquant.co`; CLI calls `/api/...` under it |
+| `NEXUSQUANT_API_BASE_URL`      | Optional full API base override, e.g. `https://api.nexusquant.co/api`                 |
+| `NEXUSQUANT_COGNITO_DOMAIN`    | Cognito Hosted UI host, default `auth.lookatwallstreet.com`                           |
+| `NEXUSQUANT_COGNITO_CLIENT_ID` | Cognito app client id                                                                 |
+| `NEXUSQUANT_REDIRECT_URI`      | OAuth callback, default `http://127.0.0.1:8251/callback`                              |
+
+There is also a hidden typo-compatible alias: `nexusquant startegy ...` maps to `nexusquant strategy ...`.