hank-risk-client 0.3.2__tar.gz

hank_risk_client-0.3.2/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: hank-risk-client
+Version: 0.3.2
+Requires-Python: >=3.11
+Requires-Dist: requests<3,>=2.32

hank_risk_client-0.3.2/README.md

@@ -0,0 +1,127 @@
+# risk_client
+
+
+`risk_client` is the thin native HTTP client for Risk's registered agent/tool surface. Code execution uses the same opaque active-cell capability as gateway frames; trusted non-code automation retains signed user claims.
+
+## Requirements
+
+`RiskClient 0.3.1` requires `RISK_API_URL` only when it issues native HTTP requests; constructing the client does not require a Risk endpoint for cells that never use it. During native code execution, the runtime supplies `AGENT_CODE_EXECUTE_CELL_TOKEN` only while the cell executes. Discovery and every raw call are verified by the Risk producer against the owning cell's current grant and explicit native registration. No signing key, broad subject bearer or TTL credential is needed in code.
+
+A retained client rereads the current token on every request, so a later cell cannot reuse an earlier grant. After release, its last token is sent to the producer and rejected there; the client does not fall back to broader signed authority.
+
+Trusted non-code callers continue to provide all seven signed-claim variables:
+
+- `AGENT_API_CLAIM_AUDIENCE`
+- `AGENT_API_CLAIM_ISSUED_AT`
+- `AGENT_API_CLAIM_EXPIRY`
+- `AGENT_API_CLAIM_USER_ID`
+- `AGENT_API_CLAIM_USER_EMAIL`
+- `AGENT_API_CLAIM_NONCE`
+- `AGENT_API_CLAIM_SIGNATURE`
+
+`RISK_API_KEY` bearer fallback is not supported by this client. The HTTP API's ordinary legacy/signed consumers remain separate and compatible; adding an invalid cell header never downgrades to either mode.
+
+## Typed Usage
+
+```python
+from risk_client import RiskClient
+
+rc = RiskClient()
+print(rc.registry())  # Current-cell native intersection, not all installed methods.
+quote = rc.get_quote(ticker="MSFT")  # Requires this producer operation in the grant.
+print(quote)
+```
+
+TypedDict return contracts are curated for the Tier A tools. Other wrappers still return `ToolResult` (`dict[str, Any]`) but keep typed parameter signatures.
+
+## Breaking Change In 0.3.0
+
+HTTP errors from `call()` and `registry()` are now wrapped in `AgentAPIError` with `.status` and `.error_type` populated. `requests.HTTPError` is no longer raised by those methods. Network errors (`ConnectionError`, `Timeout`, SSL) propagate unchanged. Server-side 404s on `call()` include a "Did you mean" suggestion when a close function name exists, and generated multi-format wrappers now include a `Formats:` line in their docstring.
+
+Before:
+
+```python
+import requests
+
+try:
+    rc.call("get_postions")
+except requests.HTTPError as e:
+    print(e)
+```
+
+After:
+
+```python
+from risk_client import AgentAPIError
+
+try:
+    rc.call("get_postions")
+except AgentAPIError as e:
+    print(e.status, e.error_type, e)
+    # 404 unknown_function get_postions: Unknown function: 'get_postions'. Did you mean 'get_positions'?
+```
+
+## Breaking Change In 0.2.0
+
+Generated wrapper methods now return the inner `result` payload and raise `AgentAPIError` on `{ok: false}` responses.
+
+Before:
+
+```python
+envelope = rc.get_positions(format="agent")
+snapshot = envelope["result"]["snapshot"]
+```
+
+After:
+
+```python
+result = rc.get_positions(format="agent")
+snapshot = result["snapshot"]
+```
+
+If you still need the raw HTTP envelope, use `call()` directly:
+
+```python
+envelope = rc.call("get_positions", format="agent")
+```
+
+If you want the same inner-result behavior used by generated wrappers, use `call_or_raise()`:
+
+```python
+result = rc.call_or_raise("get_positions", format="agent")
+```
+
+## Standalone Installation
+
+`RISK_CLIENT_PATH` names the Risk checkout root, not the `risk_client` directory.
+Install the local package into the interpreter that will run your code:
+
+```bash
+export RISK_CLIENT_PATH=/path/to/risk_module
+python -m pip install "$RISK_CLIENT_PATH/risk_client"
+python -c 'from risk_client import RiskClient; print("RiskClient import OK")'
+```
+
+The distribution includes the client, return types, and shared telemetry header
+contract. It needs only its declared `requests` dependency, not the Risk backend
+or a checkout entry on `PYTHONPATH`. Creating a client requires either the
+executing cell's opaque token or the ordinary signed-claim environment.
+Call and registry requests additionally require the configured API URL.
+
+## Code-executor installation and attribution
+
+Supported product executors install the narrow client artifact from the selected
+Risk revision. Do not expose the backend checkout or rely on a mounted source
+tree to repair a missing SDK.
+
+Native call envelopes add canonical parent/nested call IDs, ordinal, operation
+and a producer-generated request ID in `meta`; ordinary envelopes are unchanged.
+The gateway's owning cell ledger retains native calls, complete deduplicated
+returned citation sources and untruncated producer computation provenance.
+`tool_version` and `output_sha256` are computation evidence, not citations.
+The gateway computation collector projects every valid native ledger entry
+into `computations`, untruncated and with its `nested_call_id`; the existing
+source consumer then recognizes actual hashes.
+The SDK does not write computation sidecar files. Native computation evidence
+is settled by the producer into the owning cell ledger; ordinary trusted HTTP
+keeps its signed authentication and response envelope without local file I/O.