@bitget-ai/getagent-skill 0.2.1

package/skills/getagent/references/sandbox-runtime.md

@@ -0,0 +1,201 @@
+# Sandbox Runtime
+
+## Contents
+
+- [Execution Model](#execution-model)
+- [State and Persistence](#state-and-persistence)
+- [Runtime Profiles](#runtime-profiles)
+- [Pre-installed Dependencies](#pre-installed-dependencies)
+- [Allowed Standard Library Modules](#allowed-standard-library-modules)
+- [Blocked Modules](#blocked-modules)
+- [Network Restrictions](#network-restrictions)
+- [Output Conventions](#output-conventions)
+- [Environment Variables](#environment-variables)
+
+## Execution Model
+
+- **Engine:** Python 3.12
+- **Entry point:** package executes as `python -m src.main`
+- **Working directory:** `/workspace/`
+- **Timeout:** 180 seconds
+- **Memory:** 2GB
+- **Fresh workspace:** Each run starts in a fresh workspace snapshot.
+- **Executable runtime profiles:** `deterministic`, plus deployment-enabled `llm_bounded`
+- **No built-in agent loop:** Do not assume planner / reflection / tool-orchestration loops are provided by the platform.
+
+## State and Persistence
+
+The workspace is ephemeral by default, but the runner may optionally hydrate and
+sync `.state/` on behalf of the Playbook.
+
+- Treat `.state/` as the only supported persisted path across runs.
+- Do not rely on files outside `.state/` surviving between runs.
+- If `.state/` hydrate fails, the runner may abort instead of silently running
+with missing state.
+- Agent memory is **not** part of the default sandbox contract. If a future
+runtime introduces agent memory, it should live behind an explicit runtime
+profile and policy.
+
+## Runtime Profiles
+
+The product direction is to separate package shape from runtime capability.
+
+- `deterministic`
+  - Current default executable profile
+  - No built-in general-purpose agent loop
+  - Best fit for `backtest_support: full`
+- `llm_bounded`
+  - Executable only when the deployment enables managed Playbook LLM access
+  - Use through `getagent.llm`, not direct HTTP clients
+  - Fixed call-count, prompt-size, output-token, and timeout budgets
+  - Best fit for `backtest_support: none`
+- `agentic`
+  - Declared contract only for now; current sandbox rejects it at runtime
+  - Should not be assumed in the default Playbook sandbox
+
+### Agent loop guidance
+
+Do **not** assume a full general-purpose agent runtime is available in the
+default Playbook sandbox.
+
+`llm_bounded` is intentionally narrower than a general-purpose agent loop. If
+the platform later introduces `agentic`, it should still require:
+
+- an explicit runtime profile or separate image
+- fixed tool allowlists
+- `max_steps`
+- `max_runtime_ms`
+- `max_model_tokens`
+- trace persistence
+- an explicit memory policy
+
+## Pre-installed Dependencies
+
+These are the packages present in the image. This is **not** the same as the
+author-facing import contract: some entries below exist only so managed SDKs can
+work internally.
+
+
+| Package           | Version             | Purpose                                                                       |
+| ----------------- | ------------------- | ----------------------------------------------------------------------------- |
+| `getagent`         | 0.1.1               | SDK (data, trade, backtest, runtime, llm)                                     |
+| `getall`          | repo source         | Internal managed runtime used by `getagent.llm`                                |
+| `litellm`         | 1.83.7              | Internal provider bridge behind `getagent.llm`                                 |
+| `trade-sdk`       | vendored source     | Internal implementation behind `getagent.trade` (not a public Playbook import) |
+| `pandas`          | ≥2.0                | Data manipulation                                                             |
+| `numpy`           | ≥1.24               | Numerical computation                                                         |
+| `nautilus_trader` | current image build | Backtest engine (used by SDK and author strategy classes)                     |
+| `pydantic`        | 2.13.2              | Internal config/runtime models                                                |
+| `pyyaml`          | ≥6.0                | YAML parsing                                                                  |
+| `matplotlib`      | ≥3.7                | Chart rendering (used by SDK internally)                                      |
+
+
+**No pip install.** PyPI is network-blocked. Only pre-installed packages are available.
+
+### Public author imports
+
+Playbook source code should import from the public surface only:
+
+- `getagent`
+- `nautilus_trader`
+- `pandas`
+- `numpy`
+- safe standard-library modules listed below
+
+Do not import implementation details such as `getall`, `litellm`, `httpx`, or
+`trade_sdk` even when they exist in the image.
+
+## Allowed Standard Library Modules
+
+`json`, `math`, `datetime`, `pathlib`, `asyncio`, `typing`, `dataclasses`,
+`collections`, `functools`, `re`, `decimal`, `statistics`, `itertools`,
+`operator`, `copy`, `enum`, `abc`, `numbers`, `fractions`
+
+## Blocked Author Imports
+
+### Security model
+
+The sandbox uses **defense in depth** — no single layer is relied on alone:
+
+1. **AST static check (best-effort):** Upload and local validation reject
+  direct `import os`, `__import__()`, `eval()`, `exec()`, `__builtins__`
+   access, and similar patterns. This catches accidental misuse and obvious
+   violations, but **cannot prevent all dynamic import bypasses** due to
+   Python's runtime flexibility.
+2. **Container image (hard boundary for the public contract):** Only
+  pre-installed packages are available. Some blocked libraries may exist as
+   internal dependencies of managed SDKs (for example `getagent.trade` is backed
+   by `trade-sdk`, and `getagent.llm` is backed by `getall` + `litellm`, which
+   use `httpx` internally), but Playbook source code is still rejected if it
+   imports those libraries directly.
+3. **Managed capability access (hard boundary):** Strategy code must fetch data
+  through `getagent.data` and place trades through `getagent.trade`. Direct HTTP
+   clients remain blocked even if the managed SDK talks to upstream services on
+   the strategy's behalf.
+4. **Container isolation (hard boundary):** The sandbox runs in an isolated
+  Docker container with resource limits. Process execution, file access,
+   and environment variable reads are confined to the container.
+
+**Standard library modules** like `os`, `subprocess`, and `importlib` are
+present in the Python runtime and cannot be removed. The AST check blocks
+direct imports, but determined bypass attempts using `getattr`/`globals()`
+are theoretically possible. These modules are considered **low risk** because
+network egress is blocked and the container is isolated.
+
+### Blocked categories
+
+**Network:** `requests`, `httpx`, `trade_sdk`, `urllib`, `aiohttp`, `socket`, `http`, `ftplib`, `smtplib`
+
+**System:** `subprocess`, `os`, `shutil`, `importlib`, `ctypes`, `multiprocessing`
+
+**Database:** `sqlalchemy`, `redis`, `pymongo`
+
+**Frameworks:** `fastapi`, `flask`, `django`
+
+**Messaging:** `telegram`, `slack_sdk`, `discord`
+
+## Network Restrictions
+
+
+| Allowed                                                                             | Blocked                                                                            |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Managed SDK data access via `getagent.data`                                          | PyPI (`pypi.org`, `files.pythonhosted.org`)                                        |
+| Trade-proxy requests via `getagent.trade` when runner context is injected            | Direct `requests` / `httpx` / `urllib` calls from Playbook code                    |
+| Managed LLM calls via `getagent.llm` when `runtime_profile: llm_bounded` is injected |                                                                                    |
+|                                                                                     | All private networks, localhost, and arbitrary public addresses from Playbook code |
+
+
+**All data fetching must go through `getagent.data`, all trade-proxy access must go through `getagent.trade`, and bounded model calls must go through `getagent.llm`.** Do not make direct HTTP requests.
+
+## Output Conventions
+
+
+| Output Type     | Mechanism                                                               | Available |
+| --------------- | ----------------------------------------------------------------------- | --------- |
+| Trading signals | `runtime.emit_signal()` → stdout JSON + `/workspace/output/signal.json` | Yes       |
+| Backtest charts | `backtest.generate_chart()` → `/workspace/output/*.png` (matplotlib)    | Yes       |
+| Debug output    | `print()` → stdout (Runner collects first 5000 chars)                   | Yes       |
+| Errors          | `print(..., file=sys.stderr)` → stderr                                  | Yes       |
+
+
+The Runner collects all `.png`, `.json`, `.csv` files from `/workspace/output/`
+as artifacts after execution completes.
+
+## Environment Variables
+
+These variables are injected by the Runner **inside the sandbox at execution time**. They are not the same as the shell variables the operator sets to call the HTTP control plane (see `references/api/upload.md`). In particular, `GETAGENT_PRINCIPAL_ID` is server-side execution context only and is **not** an HTTP auth credential — prod OpenAPI client calls must use `ACCESS-KEY`, never `X-Principal-Id`.
+
+| Variable                       | Description                                                                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `GETAGENT_WORKSPACE`            | Working directory path (default `/workspace`)                                                                                        |
+| `GETAGENT_RUN_ID`               | Unique run identifier                                                                                                                |
+| `GETAGENT_PLAYBOOK_ID`          | Playbook ID                                                                                                                          |
+| `GETAGENT_PRINCIPAL_ID`         | Execution principal for the current run (sandbox-injected; **not** for HTTP client auth)                                              |
+| `GETAGENT_CHAT_ID`              | Delivery target for manual or scheduled results                                                                                      |
+| `GETAGENT_DATA_BASE_URL`        | Preferred data API base URL for `getagent.data`                                                                                       |
+| `OPENBB_BASE_URL`              | Legacy compatibility alias for `getagent.data`                                                                                        |
+| `GETAGENT_TRADE_BG_UID`         | Trade-proxy subaccount identifier used by `getagent.trade`                                                                            |
+| `GETAGENT_TRADE_PROXY_BASE_URL` | Trade-proxy base URL injected by the runner                                                                                          |
+| `GETAGENT_TRADE_CHANNEL`        | Trade-proxy channel label injected by the runner                                                                                     |
+| `GETAGENT_RUNTIME_PROFILE`      | Runner-selected runtime profile for the current execution                                                                            |
+| `GETAGENT_LLM_`*                | Internal bounded LLM config injected only for `runtime_profile: llm_bounded`; prefer `getagent.llm` instead of reading these directly |

package/skills/getagent/references/sdk/backtest/catalog.md

@@ -0,0 +1,208 @@
+# `getagent.backtest`
+
+Author-facing replay and charting surface for backtestable Playbooks.
+
+## When to use
+
+Use `getagent.backtest` when the core trading decision can be fairly
+reconstructed from historical data and expressed as a NautilusTrader strategy.
+
+Typical fit:
+
+- `runtime_profile: deterministic`
+- `backtest_support: full`
+- strategy logic implemented as a `nautilus_trader.trading.strategy.Strategy`
+  subclass under `src/**`
+- historical metrics intended for public evidence
+
+Do not use `getagent.backtest` to justify strategies whose trade decision
+depends on open-ended LLM reasoning or unreplayable live context.
+
+## Public API
+
+### Prepare one dataset
+
+- `backtest.prepare_frame(source, datetime_index=None, rename_columns=None) -> pandas.DataFrame`
+
+Behavior:
+
+- accepts `OBBject`, `pandas.DataFrame`, one mapping, or a list of mappings
+- normalizes column names to lowercase
+- parses the time column into a UTC `DatetimeIndex`
+
+### Describe one feature source
+
+- `backtest.FeatureSource(...)`
+
+Useful fields:
+
+- `data` — one historical dataset returned by `getagent.data` or already prepared locally
+- `datetime_index` — time field name when the source is not already indexed
+- `rename_columns` — rename raw source fields into replay-field names such as
+  `taker_buy_volume`
+- `include_columns` — keep only the columns you want to attach to the replay frame
+- `prefix` — add a prefix to every attached feature column
+- `mode` — `"asof"` for time alignment or `"exact"` for exact index joins
+- `join` — `"left"` (default) or `"inner"`
+- `direction` / `tolerance` — `merge_asof` controls for time-series joins
+
+### Build one replay frame
+
+- `backtest.build_feature_frame(base, base_datetime_index=None, base_rename_columns=None, features=None) -> pandas.DataFrame`
+
+Behavior:
+
+- starts from a base bar dataset, usually K lines / candles
+- aligns arbitrary historical feature datasets onto the base timestamps
+- returns one replay-ready DataFrame that still contains core OHLCV plus your
+  added feature columns
+
+### Run a backtest
+
+- `backtest.run(ohlcv_data, spec=None) -> BacktestResult`
+
+Parameters:
+
+- `ohlcv_data`
+  - dict of `{instrument-key: pandas.DataFrame}`
+  - each frame should have a `DatetimeIndex` plus OHLCV columns
+  - additional normalized columns are preserved for strategy feature access
+  - keys should match the instrument IDs or symbols declared in `backtest.yaml`
+
+- `spec`
+  - usually `runtime.backtest_spec`
+  - explicit Nautilus backtest spec with:
+    - `venue`
+    - `instrument` or `instruments`
+    - `strategy`
+    - optional `execution`
+    - optional `data_requirements.required_bar_fields`
+
+### Generate a chart
+
+- `backtest.generate_chart(result, save_dir=None) -> str`
+
+Behavior:
+
+- writes a PNG to `/workspace/output/` by default
+- returns the saved path as a string
+- returns `""` when chart generation fails
+
+## Result shape
+
+`BacktestResult` exposes normalized account-level summary metrics directly:
+
+- `total_return_pct` (account return, using `backtest.yaml` starting balance)
+- `sharpe_ratio`
+- `max_drawdown_pct`
+- `win_rate`
+- `profit_factor`
+- `total_trades`
+- `summary`
+- `raw`
+
+User-facing return % is computed by the platform on a per-strategy basis
+(`net_pnl / manifest.strategy_config.margin_budget`). The author should emit
+the engine summary as-is; `service.build_run_record` rewrites
+`total_return_pct` and `max_drawdown_pct` before storing them, preserving the
+account-level numbers as `account_total_return_pct` /
+`account_max_drawdown_pct` for analysts. Just remember to declare a positive
+`margin_budget` in `manifest.strategy_config` (validation requires it for
+`backtest_support: full` and `execution_mode: follow_trade`).
+
+`result.raw` is Nautilus-native output with stable top-level sections:
+
+- `summary` — normalized key metrics
+- `stats` — analyzer outputs grouped by returns / general / pnls
+- `reports` — account / orders / fills / positions / equity curve
+- `config` — the resolved venue, instrument IDs, bar types, and strategy entry
+
+## Example
+
+```python
+from getagent import backtest, data, runtime
+
+bars = data.crypto.futures.kline(symbol="BTCUSDT", interval="1h", exchange="binance")
+taker_volume = data.crypto.futures.taker_volume(symbol="BTCUSDT", period="1h")
+open_interest = data.crypto.futures.open_interest_history(symbol="BTCUSDT", period="1h")
+
+replay_frame = backtest.build_feature_frame(
+    bars,
+    base_datetime_index="date",
+    features=[
+        backtest.FeatureSource(
+            data=taker_volume,
+            datetime_index="timestamp",
+            include_columns=("buy_vol", "sell_vol"),
+            rename_columns={
+                "buy_vol": "taker_buy_volume",
+                "sell_vol": "taker_sell_volume",
+            },
+        ),
+        backtest.FeatureSource(
+            data=open_interest,
+            datetime_index="date",
+            include_columns=("open_interest",),
+        ),
+    ],
+)
+
+result = backtest.run(
+    ohlcv_data={"BTCUSDT.BINANCE": replay_frame},
+    spec=runtime.backtest_spec,
+)
+
+chart_path = backtest.generate_chart(result)
+summary = result.summary
+net_pnl = float(summary.get("net_pnl", 0) or 0)
+
+runtime.emit_signal(
+    action="long" if net_pnl > 0 else "hold",
+    symbol="BTCUSDT",
+    confidence=result.win_rate,
+    metrics={
+        "total_return_pct": result.total_return_pct,
+        "net_pnl": net_pnl,
+        "starting_balance": summary.get("starting_balance"),
+        "sharpe_ratio": result.sharpe_ratio,
+        "max_drawdown_pct": result.max_drawdown_pct,
+        "win_rate": result.win_rate,
+        "total_trades": result.total_trades,
+        "profit_factor": result.profit_factor,
+    },
+    meta={"chart_path": chart_path},
+)
+```
+
+## Hard rules
+
+- Use `runtime.backtest_spec` as the default source of replay configuration
+- Keep public backtest claims tied to deterministic strategy logic
+- Declare enriched replay column dependencies in
+  `backtest.yaml -> data_requirements.required_bar_fields`
+- Use `prepare_frame()` / `build_feature_frame()` to standardize multi-endpoint
+  replay assembly instead of open-coded timestamp joins
+- Expect `backtest.run()` to fail fast when declared replay columns are missing
+  or all-null in the effective execution window
+- Before making a backtest claim, verify the replay frame covers the claimed
+  window and contains every decision feature. Record row count, first/last
+  timestamp, and returned fields during probing.
+- Do not silently replace missing decision features with constants such as
+  `0`, `0.5`, or `False`. Missing `taker_buy_ratio`, open interest, funding, or
+  liquidation data should either fail the run or be reported as degraded, not
+  hidden inside the performance metrics.
+- Strategy classes may import `nautilus_trader`; Playbook code must not import
+  legacy backtest engines directly
+- Do not use `backtest.run()` as fake evidence for `llm_bounded` strategies
+- Treat `result.total_trades == 0` as a diagnostic case, not a success story
+- Prefer `generate_chart(result)` over writing ad hoc chart files yourself
+- Do not emit `metrics=result.summary` directly for user-visible backtest
+  results when the strategy has a configured budget. Convert `net_pnl` to
+  strategy-budget return and keep account return under `account_return_pct`.
+
+## Related docs
+
+- [`../../backtest-engine.md`](../../backtest-engine.md)
+- [`../../package-schema.md`](../../package-schema.md)
+- [`../../sandbox-runtime.md`](../../sandbox-runtime.md)
+- [`../runtime/catalog.md`](../runtime/catalog.md)

package/skills/getagent/references/sdk/data/arxiv.md

@@ -0,0 +1,41 @@
+# Arxiv Data Reference
+
+Use this file when an agent needs detailed signatures and parameter
+rules for one DataSDK domain. All generated `getagent.data` endpoints
+are callable through the DataSDK wrapper.
+
+## Contents
+- [`arxiv.search`](#arxivsearch)
+
+## Endpoint reference
+
+### `arxiv.search`
+
+```python
+data.arxiv.search(query=None, max_results=10, page=1, sort_by='relevance', sort_order='descending', search_field='all', category=None, provider='arxiv')
+```
+
+Summary: Search
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `arxiv.search` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/arxiv/search` |
+| Default provider | `arxiv` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `query` | `no` | `string | null` | `-` | Search query string. (provider: arxiv) |
+| `max_results` | `no` | `integer` | `10` | Maximum number of results. (provider: arxiv) |
+| `page` | `no` | `integer` | `1` | Page number, starting at 1. (provider: arxiv) |
+| `sort_by` | `no` | `string` | `relevance` | Sort by relevance, last updated date, or submitted date. (provider: arxiv) |
+| `sort_order` | `no` | `string` | `descending` | Sort direction. (provider: arxiv) |
+| `search_field` | `no` | `string` | `all` | Field to search: all, ti (title), au (author), abs (abstract), cat (category). (provider: arxiv) |
+| `category` | `no` | `string | null` | `-` | Filter by arXiv subject category, e.g. 'cs.AI', 'q-fin.TR'. (provider: arxiv) |
+| `provider` | `no` | `string` | `arxiv` | - |

package/skills/getagent/references/sdk/data/catalog.md

@@ -0,0 +1,56 @@
+# Data Reference Catalog
+
+This catalog is the self-contained runtime reference for `getagent.data`.
+All links in this directory stay inside the packaged runtime skill so an
+agent can inspect DataSDK endpoint contracts without depending on the
+Playbook creator source tree.
+
+## Read order
+
+1. Start with [`playbook-supported.md`](playbook-supported.md) for the full
+   Playbook-callable `getagent.data` surface.
+2. Use the domain files below for exact signatures, defaults, enums,
+   provider notes, and parameter details.
+
+## Domain index
+
+| Domain | File | Endpoints |
+|---|---|---:|
+| `Coverage` | [coverage.md](coverage.md) | 3 |
+| `arxiv` | [arxiv.md](arxiv.md) | 1 |
+| `commodity` | [commodity.md](commodity.md) | 7 |
+| `crypto` | [crypto.md](crypto.md) | 97 |
+| `currency` | [currency.md](currency.md) | 4 |
+| `derivatives` | [derivatives.md](derivatives.md) | 8 |
+| `economy` | [economy.md](economy.md) | 42 |
+| `equity` | [equity.md](equity.md) | 68 |
+| `etf` | [etf.md](etf.md) | 12 |
+| `famafrench` | [famafrench.md](famafrench.md) | 6 |
+| `fixedincome` | [fixedincome.md](fixedincome.md) | 25 |
+| `imf_utils` | [imf_utils.md](imf_utils.md) | 8 |
+| `index` | [index.md](index.md) | 7 |
+| `news` | [news.md](news.md) | 3 |
+| `regulators` | [regulators.md](regulators.md) | 10 |
+| `sentiment` | [sentiment.md](sentiment.md) | 11 |
+| `uscongress` | [uscongress.md](uscongress.md) | 4 |
+| `web_search` | [web_search.md](web_search.md) | 2 |
+| `wikipedia` | [wikipedia.md](wikipedia.md) | 3 |
+
+## Notes
+
+- Status rows are generated from the same availability registry used by
+  the SDK tests and runtime metadata.
+- Playbook sandboxes are expected to support the complete generated
+  `getagent.data` namespace. Do not treat data endpoints as having a
+  separate sandbox allowlist.
+- For backtests, verify the endpoint returns the fields and time axis your
+  strategy needs before declaring those fields in `backtest.yaml`.
+- `provider` may be shown with a default even when the upstream OpenAPI
+  marks it as required. That reflects the managed `getagent.data` wrapper,
+  which auto-injects the default provider when one is defined.
+- Time ranges use millisecond Unix-epoch `start_time` / `end_time` and the
+  canonical datetime column is `time`. The SDK still accepts the legacy
+  `start_date` / `end_date` parameters (and exposes a derived `date` field)
+  with a `DeprecationWarning` until upstream removes the legacy surface.
+  Call `data.to_dataframe(bars)` without `datetime_index` to let the SDK
+  pick the canonical column.