nexusquant-sdk 0.1.0__tar.gz

nexusquant_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.DS_Store
+/.idea

nexusquant_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: nexusquant-sdk
+Version: 0.1.0
+Summary: NexusQuant strategy provider Python SDK
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Description-Content-Type: text/markdown
+
+# nexusquant-sdk
+
+NexusQuant 量化策略提供者 Python SDK，用于在 NexusQuant 平台上注册、管理量化策略并发送交易信号。
+
+## 安装
+
+```bash
+pip install nexusquant-sdk
+```
+
+依赖 Python 3.10 及以上版本。
+
+## 快速开始
+
+```python
+import nexusquant_sdk as nq
+
+# 登录（首次使用，会打开浏览器完成授权）
+nq.auth_login()
+
+# 查看已注册的策略列表
+strategies = nq.strategy_list()
+
+# 发送单笔交易信号
+nq.strategy_send_signal_single(
+    "my_alpha",
+    ticker="AAPL",
+    direction="buy",    # "buy" 或 "sell"
+    price=150.0,
+    quantity=100,       # 股数
+    order_type="LIMIT", # "MARKET" 或 "LIMIT"
+)
+```
+
+## 认证
+
+SDK 使用 OAuth 2.0 PKCE 流程完成登录，令牌存储在本地，无需每次重新登录。
+
+```python
+nq.auth_login()            # 打开浏览器完成登录，保存令牌到本地
+nq.auth_logged_in()        # 检查是否已登录，返回 True/False
+nq.auth_refresh()          # 使用 refresh token 刷新 ID token
+nq.auth_logout()           # 删除本地令牌，退出登录
+nq.auth_credentials_path() # 查看令牌文件的本地路径
+```
+
+## 策略管理
+
+```python
+# 注册或更新策略
+nq.strategy_register("my_alpha", "我的 Alpha 策略", output_unit="SHARE_COUNT")
+
+# 查询策略列表
+nq.strategy_list()
+
+# 查询信号历史
+nq.strategy_signal_history("my_alpha", limit=20)
+
+# 发送单笔信号
+nq.strategy_send_signal_single(
+    "my_alpha",
+    ticker="AAPL",
+    direction="buy",
+    price=150.0,
+    quantity=100,
+    order_type="LIMIT",
+)
+
+# 批量发送信号（多路由映射）
+nq.strategy_send_signals("my_alpha", {"default": { ... }})
+
+# 从本地 JSON 文件发送信号
+nq.strategy_send_signals_from_path("my_alpha", "signals.json")
+
+# 查询订阅者配置快照
+nq.strategy_subscriber_config("my_alpha")
+```
+
+## 环境变量配置
+
+可通过以下环境变量覆盖默认配置：
+
+| 变量名 | 说明 |
+|---|---|
+| `NEXUSQUANT_API_ENDPOINT` | API 服务地址（默认：`https://api.nexusquant.co`） |
+| `NEXUSQUANT_COGNITO_DOMAIN` | 认证服务域名 |
+| `NEXUSQUANT_COGNITO_CLIENT_ID` | OAuth 客户端 ID |
+| `NEXUSQUANT_REDIRECT_URI` | OAuth 回调地址（默认：`http://127.0.0.1:8251/callback`） |
+
+## 依赖
+
+- Python 3.10+
+- `httpx >= 0.27`
+- `platformdirs >= 4.2`

nexusquant_sdk-0.1.0/README.md

@@ -0,0 +1,94 @@
+# nexusquant-sdk
+
+NexusQuant 量化策略提供者 Python SDK，用于在 NexusQuant 平台上注册、管理量化策略并发送交易信号。
+
+## 安装
+
+```bash
+pip install nexusquant-sdk
+```
+
+依赖 Python 3.10 及以上版本。
+
+## 快速开始
+
+```python
+import nexusquant_sdk as nq
+
+# 登录（首次使用，会打开浏览器完成授权）
+nq.auth_login()
+
+# 查看已注册的策略列表
+strategies = nq.strategy_list()
+
+# 发送单笔交易信号
+nq.strategy_send_signal_single(
+    "my_alpha",
+    ticker="AAPL",
+    direction="buy",    # "buy" 或 "sell"
+    price=150.0,
+    quantity=100,       # 股数
+    order_type="LIMIT", # "MARKET" 或 "LIMIT"
+)
+```
+
+## 认证
+
+SDK 使用 OAuth 2.0 PKCE 流程完成登录，令牌存储在本地，无需每次重新登录。
+
+```python
+nq.auth_login()            # 打开浏览器完成登录，保存令牌到本地
+nq.auth_logged_in()        # 检查是否已登录，返回 True/False
+nq.auth_refresh()          # 使用 refresh token 刷新 ID token
+nq.auth_logout()           # 删除本地令牌，退出登录
+nq.auth_credentials_path() # 查看令牌文件的本地路径
+```
+
+## 策略管理
+
+```python
+# 注册或更新策略
+nq.strategy_register("my_alpha", "我的 Alpha 策略", output_unit="SHARE_COUNT")
+
+# 查询策略列表
+nq.strategy_list()
+
+# 查询信号历史
+nq.strategy_signal_history("my_alpha", limit=20)
+
+# 发送单笔信号
+nq.strategy_send_signal_single(
+    "my_alpha",
+    ticker="AAPL",
+    direction="buy",
+    price=150.0,
+    quantity=100,
+    order_type="LIMIT",
+)
+
+# 批量发送信号（多路由映射）
+nq.strategy_send_signals("my_alpha", {"default": { ... }})
+
+# 从本地 JSON 文件发送信号
+nq.strategy_send_signals_from_path("my_alpha", "signals.json")
+
+# 查询订阅者配置快照
+nq.strategy_subscriber_config("my_alpha")
+```
+
+## 环境变量配置
+
+可通过以下环境变量覆盖默认配置：
+
+| 变量名 | 说明 |
+|---|---|
+| `NEXUSQUANT_API_ENDPOINT` | API 服务地址（默认：`https://api.nexusquant.co`） |
+| `NEXUSQUANT_COGNITO_DOMAIN` | 认证服务域名 |
+| `NEXUSQUANT_COGNITO_CLIENT_ID` | OAuth 客户端 ID |
+| `NEXUSQUANT_REDIRECT_URI` | OAuth 回调地址（默认：`http://127.0.0.1:8251/callback`） |
+
+## 依赖
+
+- Python 3.10+
+- `httpx >= 0.27`
+- `platformdirs >= 4.2`

nexusquant_sdk-0.1.0/nexusquant_sdk/__init__.py

@@ -0,0 +1,34 @@
+__version__ = "0.1.0"
+
+from nexusquant_sdk._core import (
+    auth_credentials_path,
+    auth_logged_in,
+    auth_login,
+    auth_logout,
+    auth_refresh,
+    get_version,
+    strategy_list,
+    strategy_register,
+    strategy_send_signal_single,
+    strategy_send_signals,
+    strategy_send_signals_from_path,
+    strategy_signal_history,
+    strategy_subscriber_config,
+)
+
+__all__ = [
+    "__version__",
+    "auth_credentials_path",
+    "auth_logged_in",
+    "auth_login",
+    "auth_logout",
+    "auth_refresh",
+    "get_version",
+    "strategy_list",
+    "strategy_register",
+    "strategy_send_signal_single",
+    "strategy_send_signals",
+    "strategy_send_signals_from_path",
+    "strategy_signal_history",
+    "strategy_subscriber_config",
+]

nexusquant_sdk-0.1.0/nexusquant_sdk/_api_client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from nexusquant_sdk._auth_pkce import ensure_fresh_id_token
+from nexusquant_sdk._config import api_base_url
+
+
+def _headers() -> dict[str, str]:
+    token = ensure_fresh_id_token()
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+    }
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        detail: Any = response.json()
+    except json.JSONDecodeError:
+        detail = response.text
+    raise RuntimeError(f"HTTP {response.status_code}: {detail}")
+
+
+def get_json(
+    path: str, *, params: dict[str, Any] | None = None, timeout: float = 60.0
+) -> Any:
+    with httpx.Client(timeout=timeout) as client:
+        response = client.get(
+            f"{api_base_url()}{path}", headers=_headers(), params=params
+        )
+    _raise_for_error(response)
+    return response.json()
+
+
+def post_json(path: str, body: Any, *, timeout: float = 60.0) -> Any:
+    headers = {**_headers(), "Content-Type": "application/json"}
+    with httpx.Client(timeout=timeout) as client:
+        response = client.post(f"{api_base_url()}{path}", headers=headers, json=body)
+    _raise_for_error(response)
+    return response.json()
+
+
+def create_strategy(body: dict[str, Any]) -> Any:
+    """POST /strategy-signal/register/ — create/update an external strategy."""
+    return post_json("/strategy-signal/register/", body)
+
+
+def list_provider_strategies() -> Any:
+    """GET /strategy-signal/provider-strategies/ — owned strategies, or all for admin."""
+    return get_json("/strategy-signal/provider-strategies/")
+
+
+def get_provider_signal_history(
+    strategy_id: str,
+    *,
+    limit: int,
+    offset: int,
+    direction: str | None = None,
+    status: str | None = None,
+) -> Any:
+    """GET /strategy-signal/provider-signals/{strategy_id}/ — scoped signal history."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if direction:
+        params["direction"] = direction
+    if status:
+        params["status"] = status
+    return get_json(f"/strategy-signal/provider-signals/{strategy_id}/", params=params)
+
+
+def send_strategy_signal(body: dict[str, Any]) -> Any:
+    """POST /strategy-signal/ — send one signal or a signals map."""
+    return post_json("/strategy-signal/", body)
+
+
+def get_subscriber_configs(strategy_id: str) -> Any:
+    """GET /strategy-signal/subscriber-configs/{strategy_id}/ — non-PII subscriber config."""
+    return get_json(f"/strategy-signal/subscriber-configs/{strategy_id}/")

nexusquant_sdk-0.1.0/nexusquant_sdk/_auth_pkce.py

@@ -0,0 +1,243 @@
+"""
+Cognito Hosted UI login via OAuth 2.0 Authorization Code + PKCE.
+
+Nexus service reads ``custom:userType`` from JWT claims for provider/admin
+authorization, so the SDK stores and sends the ID token as ``Authorization:
+Bearer``. Refresh uses the Cognito refresh token when the ID token is near expiry.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+import httpx
+
+from nexusquant_sdk._config import (
+    clear_credentials,
+    cognito_client_id,
+    cognito_domain_host,
+    load_credentials,
+    redirect_uri,
+    save_credentials,
+)
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(48)
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def _parse_query(path: str) -> dict[str, str]:
+    query = urllib.parse.urlparse(path).query
+    return dict(urllib.parse.parse_qsl(query))
+
+
+def _token_url(domain_host: str) -> str:
+    return f"https://{domain_host}/oauth2/token"
+
+
+def _post_token(domain_host: str, body: dict[str, Any]) -> dict[str, Any]:
+    with httpx.Client(timeout=30.0) as client:
+        response = client.post(
+            _token_url(domain_host),
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+    if response.status_code >= 400:
+        try:
+            detail: Any = response.json()
+        except json.JSONDecodeError:
+            detail = response.text
+        raise RuntimeError(
+            f"Cognito token endpoint error ({response.status_code}): {detail}"
+        )
+    return response.json()
+
+
+def refresh_tokens(
+    *,
+    domain_host: str,
+    client_id: str,
+    refresh_token: str,
+) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+    )
+
+
+def exchange_code_for_tokens(
+    *,
+    domain_host: str,
+    client_id: str,
+    code: str,
+    redirect_uri_value: str,
+    code_verifier: str,
+) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "authorization_code",
+            "client_id": client_id,
+            "code": code,
+            "redirect_uri": redirect_uri_value,
+            "code_verifier": code_verifier,
+        },
+    )
+
+
+def run_browser_login() -> dict[str, Any]:
+    domain_host = cognito_domain_host()
+    client_id = cognito_client_id()
+    redirect_uri_value = redirect_uri()
+    verifier, challenge = _pkce_pair()
+
+    auth_params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri_value,
+        "scope": "openid email phone",
+        "code_challenge_method": "S256",
+        "code_challenge": challenge,
+    }
+    auth_url = (
+        f"https://{domain_host}/oauth2/authorize?{urllib.parse.urlencode(auth_params)}"
+    )
+
+    code_holder: dict[str, str | None] = {"code": None, "error": None}
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, _format: str, *_args: object) -> None:
+            return
+
+        def do_GET(self) -> None:  # noqa: N802
+            params = _parse_query(self.path)
+            if "code" in params:
+                code_holder["code"] = params["code"]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    b"<html><body><p>NexusQuant login successful. You can close this tab.</p></body></html>"
+                )
+            else:
+                error = (
+                    params.get("error_description")
+                    or params.get("error")
+                    or "unknown_error"
+                )
+                code_holder["error"] = error
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    f"<html><body><p>NexusQuant login failed: {error}</p></body></html>".encode(
+                        "utf-8"
+                    )
+                )
+            done.set()
+
+    parsed = urllib.parse.urlparse(redirect_uri_value)
+    if parsed.hostname not in ("127.0.0.1", "localhost") or not parsed.port:
+        raise RuntimeError("NEXUSQUANT_REDIRECT_URI must be localhost with a port.")
+
+    bind_host = "127.0.0.1" if parsed.hostname == "localhost" else parsed.hostname
+    server = HTTPServer((bind_host or "127.0.0.1", parsed.port), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    webbrowser.open(auth_url)
+
+    if not done.wait(timeout=300):
+        server.shutdown()
+        raise TimeoutError("No OAuth callback received within 5 minutes.")
+    server.shutdown()
+
+    if code_holder["error"]:
+        raise RuntimeError(f"Cognito error: {code_holder['error']}")
+    code = code_holder["code"]
+    if not code:
+        raise RuntimeError("No authorization code in callback.")
+
+    tokens = exchange_code_for_tokens(
+        domain_host=domain_host,
+        client_id=client_id,
+        code=code,
+        redirect_uri_value=redirect_uri_value,
+        code_verifier=verifier,
+    )
+    if "id_token" not in tokens:
+        raise RuntimeError("Cognito token response missing id_token.")
+    return tokens
+
+
+def persist_tokens(tokens: dict[str, Any]) -> None:
+    save_credentials(
+        {
+            "id_token": tokens["id_token"],
+            "access_token": tokens.get("access_token"),
+            "refresh_token": tokens.get("refresh_token"),
+            "expires_in": int(tokens.get("expires_in") or 0),
+            "saved_at": time.time(),
+        }
+    )
+
+
+def ensure_fresh_id_token(*, force_refresh: bool = False) -> str:
+    creds = load_credentials()
+    if not creds or not creds.get("id_token"):
+        raise RuntimeError("Not logged in. Please call auth_login() first.")
+
+    expires_in = int(creds.get("expires_in") or 0)
+    saved_at = float(creds.get("saved_at") or 0)
+    remaining = saved_at + expires_in - time.time() if expires_in > 0 else 999999
+    refresh_token = creds.get("refresh_token")
+    if not force_refresh and (remaining > 120 or not refresh_token):
+        return str(creds["id_token"])
+    if not refresh_token:
+        return str(creds["id_token"])
+
+    try:
+        new_tokens = refresh_tokens(
+            domain_host=cognito_domain_host(),
+            client_id=cognito_client_id(),
+            refresh_token=refresh_token,
+        )
+    except RuntimeError as exc:
+        if "invalid_grant" in str(exc):
+            clear_credentials()
+            raise RuntimeError(
+                "Refresh token expired or revoked. Please call auth_login() again."
+            ) from exc
+        raise
+    merged = {
+        "id_token": new_tokens.get("id_token") or creds["id_token"],
+        "access_token": new_tokens.get("access_token") or creds.get("access_token"),
+        "refresh_token": new_tokens.get("refresh_token") or refresh_token,
+        "expires_in": int(new_tokens.get("expires_in") or expires_in),
+        "saved_at": time.time(),
+    }
+    save_credentials(merged)
+    return str(merged["id_token"])
+
+
+def login_and_save() -> None:
+    persist_tokens(run_browser_login())

nexusquant_sdk-0.1.0/nexusquant_sdk/_config.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+CONFIG_DIR = Path(user_config_dir("nexusquant-sdk", appauthor=False))
+CREDENTIALS_PATH = CONFIG_DIR / "credentials.json"
+
+DEFAULT_API_ENDPOINT = "https://api.nexusquant.co"
+DEFAULT_COGNITO_DOMAIN = "auth.lookatwallstreet.com"
+DEFAULT_COGNITO_CLIENT_ID = "5o7hhd4hn4birr8c29vndehiat"
+DEFAULT_REDIRECT_URI = "http://127.0.0.1:8251/callback"
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name)
+    if value is not None and value.strip():
+        return value.strip()
+    return default
+
+
+def api_base_url() -> str:
+    endpoint = (
+        _env("NEXUSQUANT_API_ENDPOINT", DEFAULT_API_ENDPOINT) or DEFAULT_API_ENDPOINT
+    ).rstrip("/")
+    base_override = _env("NEXUSQUANT_API_BASE_URL")
+    if base_override:
+        return base_override.rstrip("/")
+    return f"{endpoint}/api"
+
+
+def cognito_domain_host() -> str:
+    domain = (
+        _env("NEXUSQUANT_COGNITO_DOMAIN", DEFAULT_COGNITO_DOMAIN)
+        or DEFAULT_COGNITO_DOMAIN
+    )
+    return domain.removeprefix("https://").removeprefix("http://").split("/")[0]
+
+
+def cognito_client_id() -> str:
+    return (
+        _env("NEXUSQUANT_COGNITO_CLIENT_ID", DEFAULT_COGNITO_CLIENT_ID)
+        or DEFAULT_COGNITO_CLIENT_ID
+    )
+
+
+def redirect_uri() -> str:
+    return _env("NEXUSQUANT_REDIRECT_URI", DEFAULT_REDIRECT_URI) or DEFAULT_REDIRECT_URI
+
+
+def load_credentials() -> dict[str, Any] | None:
+    if not CREDENTIALS_PATH.is_file():
+        return None
+    try:
+        return json.loads(CREDENTIALS_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_credentials(data: dict[str, Any]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    try:
+        CREDENTIALS_PATH.chmod(0o600)
+    except OSError:
+        pass
+
+
+def clear_credentials() -> None:
+    try:
+        CREDENTIALS_PATH.unlink(missing_ok=True)
+    except OSError:
+        pass

nexusquant_sdk-0.1.0/nexusquant_sdk/_core.py

@@ -0,0 +1,282 @@
+"""
+Public SDK functions for the NexusQuant provider API.
+
+Each function maps to an endpoint (and mirrors a CLI command).
+Successful calls return the parsed JSON response (``dict`` / ``list`` / etc.).
+Errors from HTTP or Cognito surface as ``RuntimeError``; invalid parameters
+raise ``ValueError``.
+
+Example::
+
+    import nexusquant_sdk as nq
+
+    nq.auth_login()                        # opens browser once
+
+    strategies = nq.strategy_list()
+    nq.strategy_send_signal_single(
+        "my_alpha",
+        ticker="AAPL",
+        direction="buy",
+        price=150.0,
+        quantity=100,
+    )
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from nexusquant_sdk import _api_client
+from nexusquant_sdk._auth_pkce import ensure_fresh_id_token, login_and_save
+from nexusquant_sdk._config import CREDENTIALS_PATH, clear_credentials, load_credentials
+
+
+def get_version() -> str:
+    """Return the installed ``nexusquant-sdk`` package version string."""
+    import nexusquant_sdk as pkg
+
+    return pkg.__version__
+
+
+def auth_login() -> None:
+    """Open the Cognito Hosted UI and persist tokens locally."""
+    login_and_save()
+
+
+def auth_refresh(*, force_refresh: bool = True) -> None:
+    """Refresh the stored ID token using the refresh token."""
+    ensure_fresh_id_token(force_refresh=force_refresh)
+
+
+def auth_logout() -> None:
+    """Remove locally saved Cognito tokens."""
+    clear_credentials()
+
+
+def auth_credentials_path() -> str:
+    """Absolute path to the local credentials file."""
+    return str(CREDENTIALS_PATH)
+
+
+def auth_logged_in() -> bool:
+    """Return ``True`` if an ID token is present locally."""
+    creds = load_credentials()
+    return bool(creds and creds.get("id_token"))
+
+
+def _read_json_path(path: Path | str, *, label: str) -> Any:
+    p = Path(path)
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except OSError as e:
+        raise ValueError(f"Cannot read {label}: {e}") from e
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{label} must contain valid JSON: {e}") from e
+
+
+def _loads_json(value: str | None, *, label: str) -> Any:
+    if value is None:
+        return None
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{label} must be valid JSON: {e}") from e
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _strategy_name_or_id(strategy_name: str | None, strategy_id: str) -> str:
+    return strategy_name or strategy_id
+
+
+def strategy_register(
+    strategy_id: str,
+    strategy_name: str,
+    *,
+    strategy_schema: dict[str, Any] | None = None,
+    strategy_schema_path: Path | str | None = None,
+    strategy_schema_json: str | None = None,
+    output_unit: str = "SHARE_COUNT",
+    description: str | None = None,
+    config: dict[str, Any] | None = None,
+    config_path: Path | str | None = None,
+    config_json: str | None = None,
+    enabled_execution_keys: list[str] | None = None,
+) -> Any:
+    """
+    Create or update an external strategy.
+
+    Supply at most one of ``strategy_schema``, ``strategy_schema_path``, or
+    ``strategy_schema_json``. If none are given, an empty object schema is used.
+    Same constraint applies to ``config`` / ``config_path`` / ``config_json``.
+    """
+    schema_sources = sum(
+        1
+        for x in (strategy_schema, strategy_schema_path, strategy_schema_json)
+        if x is not None
+    )
+    if schema_sources > 1:
+        raise ValueError(
+            "Use only one of strategy_schema, strategy_schema_path, strategy_schema_json."
+        )
+    config_sources = sum(1 for x in (config, config_path, config_json) if x is not None)
+    if config_sources > 1:
+        raise ValueError("Use only one of config, config_path, config_json.")
+
+    if strategy_schema is not None:
+        resolved_schema: dict[str, Any] = strategy_schema
+    elif strategy_schema_path is not None:
+        loaded = _read_json_path(strategy_schema_path, label="strategy schema")
+        if not isinstance(loaded, dict):
+            raise ValueError("strategy schema file must contain a JSON object.")
+        resolved_schema = loaded
+    elif strategy_schema_json is not None:
+        loaded = _loads_json(strategy_schema_json, label="strategy schema")
+        if not isinstance(loaded, dict):
+            raise ValueError("strategy_schema_json must decode to a JSON object.")
+        resolved_schema = loaded
+    else:
+        resolved_schema = {"type": "object", "properties": {}, "required": []}
+
+    resolved_config: dict[str, Any] | None = None
+    if config is not None:
+        resolved_config = config
+    elif config_path is not None:
+        loaded = _read_json_path(config_path, label="strategy config")
+        if not isinstance(loaded, dict):
+            raise ValueError("strategy config file must contain a JSON object.")
+        resolved_config = loaded
+    elif config_json is not None:
+        loaded = _loads_json(config_json, label="strategy config")
+        if not isinstance(loaded, dict):
+            raise ValueError("config_json must decode to a JSON object.")
+        resolved_config = loaded
+
+    body: dict[str, Any] = {
+        "strategy_id": strategy_id,
+        "strategy_name": strategy_name,
+        "strategy_schema": resolved_schema,
+        "output_unit": output_unit,
+    }
+    if description is not None:
+        body["description"] = description
+    if resolved_config is not None:
+        body["config"] = resolved_config
+    if enabled_execution_keys is not None:
+        body["enabled_execution_keys"] = enabled_execution_keys
+    return _api_client.create_strategy(body)
+
+
+def strategy_list() -> Any:
+    """List provider strategies."""
+    return _api_client.list_provider_strategies()
+
+
+def strategy_signal_history(
+    strategy_id: str,
+    *,
+    limit: int = 50,
+    offset: int = 0,
+    direction: str | None = None,
+    status: str | None = None,
+) -> Any:
+    """Fetch signal history for a strategy."""
+    return _api_client.get_provider_signal_history(
+        strategy_id,
+        limit=limit,
+        offset=offset,
+        direction=direction,
+        status=status,
+    )
+
+
+def strategy_send_signals(
+    strategy_id: str,
+    signals: dict[str, Any],
+    *,
+    strategy_name: str | None = None,
+) -> Any:
+    """
+    Send a multi-route ``signals`` map.
+
+    ``signals`` keys are ``"default"`` or user ids; values are per-route signal objects.
+    """
+    if not isinstance(signals, dict):
+        raise ValueError("signals must be a dict (JSON object).")
+    body: dict[str, Any] = {
+        "strategy_id": strategy_id,
+        "strategy_name": _strategy_name_or_id(strategy_name, strategy_id),
+        "signals": signals,
+    }
+    return _api_client.send_strategy_signal(body)
+
+
+def strategy_send_signals_from_path(
+    strategy_id: str,
+    signals_path: Path | str,
+    *,
+    strategy_name: str | None = None,
+) -> Any:
+    """Load a UTF-8 JSON object from disk and send it as ``signals``."""
+    data = _read_json_path(signals_path, label="signals map")
+    if not isinstance(data, dict):
+        raise ValueError("signals file must contain a JSON object.")
+    return strategy_send_signals(strategy_id, data, strategy_name=strategy_name)
+
+
+def strategy_send_signal_single(
+    strategy_id: str,
+    *,
+    ticker: str,
+    direction: str,
+    price: float,
+    quantity: int,
+    strategy_name: str | None = None,
+    time_iso: str | None = None,
+    order_type: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Any:
+    """
+    Send a single signal for a strategy.
+
+    ``direction`` must be ``"buy"`` or ``"sell"``.
+    ``quantity`` is share count (positive integer).
+    ``order_type`` may be ``"MARKET"``, ``"LIMIT"``, or legacy ``"NORMAL"`` (treated as LIMIT).
+    """
+    direction_norm = direction.strip().lower()
+    if direction_norm not in ("buy", "sell"):
+        raise ValueError('direction must be "buy" or "sell".')
+    if int(quantity) <= 0:
+        raise ValueError("quantity must be a positive integer.")
+    signal: dict[str, Any] = {
+        "ticker": ticker,
+        "time": time_iso or _now_iso(),
+        "price": price,
+        "direction": direction_norm,
+        "quantity": int(quantity),
+    }
+    if order_type is not None:
+        normalized = order_type.strip().upper()
+        if normalized == "NORMAL":
+            normalized = "LIMIT"
+        if normalized not in {"MARKET", "LIMIT"}:
+            raise ValueError('order_type must be "MARKET", "LIMIT", or legacy "NORMAL".')
+        signal["order_type"] = normalized
+    if metadata is not None:
+        signal["metadata"] = metadata
+    body: dict[str, Any] = {
+        "strategy_id": strategy_id,
+        "strategy_name": _strategy_name_or_id(strategy_name, strategy_id),
+        "signal": signal,
+    }
+    return _api_client.send_strategy_signal(body)
+
+
+def strategy_subscriber_config(strategy_id: str) -> Any:
+    """Return non-PII subscriber configuration snapshot for a strategy."""
+    return _api_client.get_subscriber_configs(strategy_id)

nexusquant_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexusquant-sdk"
+version = "0.1.0"
+description = "NexusQuant strategy provider Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27",
+  "platformdirs>=4.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["nexusquant_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"