@bitget-ai/getagent-skill 0.2.1

package/skills/getagent/references/api/run.md

@@ -0,0 +1,149 @@
+# Run Playbook Backtest / Evaluation
+
+Trigger a single evaluation run. This endpoint is asynchronous: it dispatches
+the run and returns a `run_id`; poll `GET /api/v1/playbook/run?run_id=...` until
+the run reaches `completed` or `failed`.
+
+## `POST /api/v1/playbook/run`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential, required on `POST /run` and `GET /run`. Missing it returns 401.
+
+**Content-Type**: `application/json`
+
+### Request
+
+```json
+{
+  "version_id": "draft-or-version-id"
+}
+```
+
+### Supported Use Cases
+
+- creator runs a draft or published Playbook to validate a new version
+- any authenticated user runs a published Playbook evaluation when `backtest_support = full`
+
+### Backtest Eligibility
+
+The endpoint is only valid for Playbooks whose public contract says they are
+fairly replayable on historical data.
+
+- `backtest_support: full` -> allowed
+- `backtest_support: none` -> reject with conflict and explain that the strategy is live-only
+- `runtime_profile: deterministic` -> allowed today
+- `runtime_profile: llm_bounded` -> reject here because this endpoint is historical evaluation only
+- `runtime_profile: agentic` -> reject until that runtime exists
+
+### Dispatch Response
+
+```json
+{
+  "run_id": "e5f6g7h8-...",
+  "strategy_id": "strategy-...",
+  "version_id": "draft-or-version-id",
+  "status": "pending",
+  "dispatched": true
+}
+```
+
+## `GET /api/v1/playbook/run?run_id=...`
+
+Poll the immutable run record created by `POST /run`.
+
+### Completed Response
+
+```json
+{
+  "run_id": "e5f6g7h8-...",
+  "playbook_id": "a1b2c3d4-...",
+  "status": "completed",
+  "active_runtime_ms": 12340,
+  "signal_output": [
+    {
+      "type": "signal",
+      "action": "long",
+      "symbol": "BTCUSDT",
+      "confidence": 0.75,
+      "metrics": {
+        "total_return_pct": 23.5,
+        "sharpe_ratio": 1.8,
+        "win_rate": 0.62
+      }
+    }
+  ],
+  "metrics_output": {
+    "total_return_pct": 23.5,
+    "sharpe_ratio": 1.8,
+    "max_drawdown_pct": 8.4,
+    "win_rate": 0.62,
+    "total_trades": 41
+  },
+  "backtest_report": {
+    "period_start": "2025-10-01T00:00:00+00:00",
+    "period_end": "2026-04-01T00:00:00+00:00"
+  },
+  "failure_reason": ""
+}
+```
+
+### Persistence Expectations
+
+Every evaluation run should be stored as immutable history, separate from
+subscription execution runs.
+
+Recommended fields to persist:
+
+- `run_kind` (`manual_backtest`)
+- `requested_by_principal_id`
+- `visibility` (`public` or `owner_only`)
+- summary metrics
+- report / chart artifact references
+
+The Playbook's official public summary should point at one designated run,
+not "whatever run happened last".
+
+### Execution Environment
+
+The Playbook runs in a dedicated `playbook_runtime` sandbox:
+
+- **Timeout**: 180 seconds
+- **Memory**: 2GB
+- **Network**: Managed data/trade access, plus managed LLM access only when `runtime_profile: llm_bounded` is injected
+- **Dependencies**: Only `getagent` + `pandas` + `numpy` (no pip install)
+- **Entry point**: Executes the package as `python -m src.main`
+
+For scheduled subscriber runs, the system executes the Playbook **once per enabled user**.
+Each run gets that user's own:
+
+- `principal_id`
+- Telegram `chat_id`
+- trade-proxy `bg_uid`
+- trade-proxy base URL
+
+That scheduled execution history should not be treated as the same thing as a
+public backtest.
+
+### Permissions
+
+- Owner can run draft and published Playbooks they control
+- Any authenticated user can run published Playbooks when `backtest_support = full`
+- Users must not be allowed to run draft versions they do not own
+
+### Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Missing `ACCESS-KEY` header |
+| 403 | Caller cannot evaluate this Playbook version, access key revoked, or principal not found / inactive |
+| 404 | `version_id` not found |
+| 409 | Playbook is live-only or uses a runtime profile that cannot run historical evaluation yet |
+| 503 | Sandbox pool not available |
+
+### On Failure
+
+`status` is `"failed"` and `failure_reason` contains the error message
+(truncated to 2000 chars). Common causes:
+
+- Data fetch timeout (exchange API unreachable)
+- `src/main.py` runtime exception
+- Timeout kill (exceeded 180 seconds)

package/skills/getagent/references/api/upload.md

@@ -0,0 +1,76 @@
+# Upload Playbook
+
+Upload a Playbook package draft to GetAgent Cloud.
+
+> Before dispatching this call, follow the **Endpoint Confirmation Discipline** in `SKILL.md` — echo a one-line preflight (`upload draft {name} → GetAgent prod https://api.bitget.com with ACCESS-KEY=<masked>`) and obtain the user's Bitget OpenAPI `ACCESS-KEY` if not already collected this session.
+
+## `POST /api/v1/playbook/upload`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+**Content-Type**: `multipart/form-data`
+
+**Body**: `package` — tar.gz file, max 10MB
+
+### Request Example
+
+Substitute `<access_key>` with the value the user provided in chat. Use the fixed GetAgent prod OpenAPI endpoint; do not parameterize it through user-provided env vars.
+
+```bash
+cd my-strategy/
+tar czf ../my-strategy.tar.gz .
+curl -X POST \
+  -H "ACCESS-KEY: <access_key>" \
+  -F "package=@../my-strategy.tar.gz" \
+  "https://api.bitget.com/api/v1/playbook/upload"
+```
+
+### Success Response
+
+```json
+{
+  "strategy_id": "strategy-...",
+  "draft_id": "draft-...",
+  "name": "btc-ema-crossover",
+  "status": "draft",
+  "suggested_version": "1.0.1"
+}
+```
+
+### Server-side Validation
+
+The server runs these checks on upload (client-side validation is not trusted):
+
+1. **Structure** — `manifest.yaml` and `src/main.py` must exist
+2. **Allowed paths only** — upload may contain `manifest.yaml`, `src/**`, and optional `backtest.yaml`
+3. **Manifest fields** — `name`, `display_name`, `description`, `market_type`, `trading_symbols`, `decision_mode`, `backtest_support`, `runtime_profile`, `execution_mode`, `follow_trade_supported` required
+4. **Name format** — DNS label (lowercase + numbers + hyphens, 1-63 chars)
+5. **Runtime contract consistency** — e.g. `runtime_profile: llm_bounded` requires `backtest_support: none`
+6. **backtest.yaml shape** — only valid when `backtest_support: full`; basic type checks enforced
+7. **Syntax** — Python files under `src/**` must compile
+8. **Import allowlist** — Only `getagent`, `pandas`, `numpy`, `json`, `math`, `datetime`, `pathlib`, `asyncio`, etc. Imports like `requests`, `subprocess`, `os` are blocked.
+9. **Version assignment** — upload never consumes a public version. The server returns a `draft_id`; the formal version is assigned later by `publish`.
+10. **Local-only paths rejected** — `tests/`, `research/`, `data/`, `output/`, caches and virtualenv folders must not be included
+
+### Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Missing `ACCESS-KEY` header |
+| 403 | Access key has been revoked, or principal not found / inactive |
+| 409 | Current state does not allow the upload operation |
+| 413 | File exceeds 10MB |
+| 422 | Validation failed — `detail.errors` contains specific error list |
+
+#### 422 Example
+
+```json
+{
+  "detail": {
+    "errors": [
+      "manifest.yaml: missing 'display_name'",
+      "src/main.py: blocked import 'requests' (line 3)"
+    ]
+  }
+}
+```

package/skills/getagent/references/backtest-engine.md

@@ -0,0 +1,438 @@
+# Backtest Engine
+
+## Contents
+
+- [Basic Usage](#basic-usage)
+- [Backtest Eligibility](#backtest-eligibility)
+- [Spec Shape](#spec-shape)
+- [Execution Model](#execution-model)
+- [BacktestResult](#backtestresult)
+- [Multi-Instrument Replays](#multi-instrument-replays)
+- [Zero-Trade Diagnostics](#zero-trade-diagnostics)
+- [Chart Generation](#chart-generation)
+
+## Basic Usage
+
+```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")
+
+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",
+            },
+        )
+    ],
+)
+
+result = backtest.run(
+    ohlcv_data={"BTCUSDT.BINANCE": replay_frame},
+    spec=runtime.backtest_spec,
+)
+chart_path = backtest.generate_chart(result)
+```
+
+## Backtest Eligibility
+
+Not every Playbook can produce a fair historical backtest.
+
+### Use the engine when:
+
+- the core trading decision is deterministic
+- the decision can be reconstructed from historical data
+- strategy logic can be expressed as a NautilusTrader `Strategy` subclass
+- any LLM usage is outside the trade decision path
+
+### Do not use the engine as public evidence when:
+
+- open-ended LLM reasoning decides whether to trade
+- the strategy depends on live chat, memory, or search context
+- the decision cannot be reconstructed at the original point in time
+
+Typical outcome:
+
+- `backtest_support: full` -> use `backtest.run()` and publish historical metrics
+- `backtest_support: none` -> use paper or live evidence instead
+
+## Spec Shape
+
+The managed engine expects an explicit Nautilus replay spec from `backtest.yaml`,
+usually read through `runtime.backtest_spec`.
+
+Required sections:
+
+- `venue`
+  - `name`
+  - `account_type`
+  - `oms_type`
+  - `starting_balances`
+- `instrument` or `instruments`
+  - `id`
+  - `kind`
+  - `raw_symbol` or `symbol`
+  - `base_currency`
+  - `quote_currency`
+  - `price_precision`
+  - `size_precision`
+  - `price_increment`
+  - `size_increment`
+  - `bar_type`
+  - perpetual instruments also need `settlement_currency`
+- `strategy`
+  - `module`
+  - `class`
+  - optional `config_class`
+  - optional `config`
+- `execution`
+  - optional `start`
+  - optional `end`
+
+## Execution Model
+
+The managed flow is:
+
+1. author code fetches historical bars through `getagent.data`
+2. `backtest.run()` normalizes each DataFrame, preserves extra replay columns,
+  and derives OHLCV bars for Nautilus
+3. the engine builds Nautilus venue + instrument definitions from `backtest.yaml`
+4. `BarDataWrangler` converts DataFrames into Nautilus bars
+5. the author's `Strategy` subclass is imported from `src/**`
+6. Nautilus `BacktestEngine` runs the replay
+7. the platform normalizes summary metrics and preserves the deeper reports
+
+For single-instrument strategies the runner auto-injects these config defaults
+when they are absent:
+
+- `instrument_id`
+- `bar_type`
+- `instrument_ids`
+- `bar_types`
+
+That means the common author pattern is:
+
+- define `DemoStrategyConfig(StrategyConfig)`
+- define `DemoStrategy(Strategy)`
+- let `backtest.yaml` carry the wiring
+
+If `backtest.yaml` declares `data_requirements.required_bar_fields`, the engine
+keeps those normalized columns on the replay DataFrames and injects the per-
+instrument frames into the strategy through `set_feature_frames(...)` or
+`strategy.feature_frames` when either hook exists.
+
+## BacktestResult
+
+
+| Property                  | Type  | Description                  |
+| ------------------------- | ----- | ---------------------------- |
+| `result.total_return_pct` | float | Account return % using the replay starting balance |
+| `result.sharpe_ratio`     | float | Sharpe ratio                 |
+| `result.max_drawdown_pct` | float | Max drawdown %               |
+| `result.win_rate`         | float | Win rate fraction (0.0-1.0)  |
+| `result.total_trades`     | int   | Total closed position count  |
+| `result.profit_factor`    | float | Profit factor                |
+| `result.summary`          | dict  | Stable normalized account-level summary |
+| `result.raw`              | dict  | Full Nautilus-derived output |
+
+`result.summary` carries account-level numbers because the engine denominator
+is `backtest.yaml.venue.starting_balances`. **You do not need to convert them
+yourself.** The platform rewrites every persisted run / package metrics block
+to the per-strategy basis (`net_pnl / manifest.strategy_config.margin_budget`)
+before storing or surfacing them on cards / Telegram pushes / run details. The
+account-level numbers are preserved alongside as `account_total_return_pct`
+and `account_max_drawdown_pct` for analysts.
+
+This is why `manifest.strategy_config.margin_budget` is **required** for
+`backtest_support: full` and `execution_mode: follow_trade` Playbooks — it is
+the declared denominator. Validation rejects manifests that omit it or set it
+to zero. If you opt out of the rewrite by hand-writing strategy-level metrics,
+also set `metrics_basis: "strategy"` in your emitted `metrics_output`; the
+platform leaves those untouched.
+
+`result.raw` keeps these top-level sections:
+
+- `summary`
+- `stats`
+- `reports`
+- `config`
+
+## Multi-Instrument Replays
+
+Use `instruments:` when the strategy needs multiple instrument definitions.
+
+Provide one OHLCV DataFrame per declared instrument ID or symbol:
+
+```python
+result = backtest.run(
+    ohlcv_data={
+        "BTCUSDT.BINANCE": btc_df,
+        "ETHUSDT.BINANCE": eth_df,
+    },
+    spec=runtime.backtest_spec,
+)
+```
+
+The engine does not synthesize cross-instrument logic for you. Multi-instrument
+behavior belongs in the author's Nautilus strategy code.
+
+## Enriched Replay Columns
+
+Core OHLCV is still the minimum contract for every replay frame. Extra columns
+such as `quote_volume`, `trade_count`, or `taker_buy_volume` can ride along in
+the same DataFrame.
+
+The standard author pattern is:
+
+1. fetch the base bar series from `getagent.data`
+2. fetch any auxiliary datasets from any supported `getagent.data` endpoints
+3. aggregate finer-grain feeds yourself when needed (for example raw trades -> hourly features)
+4. use `backtest.build_feature_frame(...)` to align those datasets onto the base bars
+5. declare the resulting feature column names in `backtest.yaml`
+
+Declare them explicitly in `backtest.yaml`:
+
+```yaml
+data_requirements:
+  required_bar_fields:
+    - quote_volume
+    - trade_count
+```
+
+Then read them from the injected feature frames in your strategy:
+
+```python
+class PriceVolStrategy(Strategy):
+    def set_feature_frames(self, feature_frames):
+        self.feature_frames = feature_frames
+
+    def on_start(self):
+        primary = self.feature_frames["BTCUSDT.BINANCE"]
+        latest_quote_volume = primary.iloc[-1]["quote_volume"]
+        # ...
+```
+
+For example, if author code builds a replay frame with
+`taker_buy_volume`, `taker_sell_volume`, and `open_interest`, those exact
+normalized names should appear under `required_bar_fields`.
+
+If a field declared in `data_requirements.required_bar_fields` is missing from a
+replay DataFrame, or exists but is entirely null inside the effective execution
+window, `backtest.run()` fails before Nautilus starts.
+
+## Zero-Trade Diagnostics
+
+If `result.total_trades == 0`, common causes are:
+
+1. bars were filtered out by `execution.start` / `execution.end`
+2. the strategy never subscribed to the declared `bar_type`
+3. instrument IDs in strategy config do not match the spec
+4. order sizing is invalid for the declared increment / lot size
+
+Inspect:
+
+- `result.raw["config"]`
+- `result.raw["reports"]["orders"]`
+- `result.raw["reports"]["fills"]`
+- `result.raw["reports"]["positions"]`
+
+## Chart Generation
+
+```python
+chart_path = backtest.generate_chart(result)
+```
+
+The managed chart renderer writes a PNG summary to `/workspace/output/`.
+
+Current chart includes:
+
+- equity curve when available
+- normalized metrics when no curve is available
+- key summary values
+# Backtest Engine
+
+## Contents
+
+- [Basic Usage](#basic-usage)
+- [Backtest Eligibility](#backtest-eligibility)
+- [Spec Shape](#spec-shape)
+- [Execution Model](#execution-model)
+- [BacktestResult](#backtestresult)
+- [Multi-Instrument Replays](#multi-instrument-replays)
+- [Zero-Trade Diagnostics](#zero-trade-diagnostics)
+- [Chart Generation](#chart-generation)
+
+## Basic Usage
+
+```python
+from getagent import backtest, data, runtime
+
+bars = data.crypto.futures.kline(symbol="BTCUSDT", interval="1h", exchange="binance")
+ohlcv = data.to_dataframe(bars, datetime_index="date")
+
+result = backtest.run(
+    ohlcv_data={"BTCUSDT.BINANCE": ohlcv},
+    spec=runtime.backtest_spec,
+)
+chart_path = backtest.generate_chart(result)
+```
+
+## Backtest Eligibility
+
+Not every Playbook can produce a fair historical backtest.
+
+### Use the engine when:
+
+- the core trading decision is deterministic
+- the decision can be reconstructed from historical data
+- strategy logic can be expressed as a NautilusTrader `Strategy` subclass
+- any LLM usage is outside the trade decision path
+
+### Do not use the engine as public evidence when:
+
+- open-ended LLM reasoning decides whether to trade
+- the strategy depends on live chat, memory, or search context
+- the decision cannot be reconstructed at the original point in time
+
+Typical outcome:
+
+- `backtest_support: full` -> use `backtest.run()` and publish historical metrics
+- `backtest_support: none` -> use paper or live evidence instead
+
+## Spec Shape
+
+The managed engine expects an explicit Nautilus replay spec from `backtest.yaml`,
+usually read through `runtime.backtest_spec`.
+
+Required sections:
+
+- `venue`
+  - `name`
+  - `account_type`
+  - `oms_type`
+  - `starting_balances`
+- `instrument` or `instruments`
+  - `id`
+  - `kind`
+  - `raw_symbol` or `symbol`
+  - `base_currency`
+  - `quote_currency`
+  - `price_precision`
+  - `size_precision`
+  - `price_increment`
+  - `size_increment`
+  - `bar_type`
+  - perpetual instruments also need `settlement_currency`
+- `strategy`
+  - `module`
+  - `class`
+  - optional `config_class`
+  - optional `config`
+- `execution`
+  - optional `start`
+  - optional `end`
+
+## Execution Model
+
+The managed flow is:
+
+1. author code fetches historical bars through `getagent.data`
+2. `backtest.run()` normalizes each DataFrame into OHLCV bars
+3. the engine builds Nautilus venue + instrument definitions from `backtest.yaml`
+4. `BarDataWrangler` converts DataFrames into Nautilus bars
+5. the author's `Strategy` subclass is imported from `src/**`
+6. Nautilus `BacktestEngine` runs the replay
+7. the platform normalizes summary metrics and preserves the deeper reports
+
+For single-instrument strategies the runner auto-injects these config defaults
+when they are absent:
+
+- `instrument_id`
+- `bar_type`
+- `instrument_ids`
+- `bar_types`
+
+That means the common author pattern is:
+
+- define `DemoStrategyConfig(StrategyConfig)`
+- define `DemoStrategy(Strategy)`
+- let `backtest.yaml` carry the wiring
+
+## BacktestResult
+
+
+| Property                  | Type  | Description                  |
+| ------------------------- | ----- | ---------------------------- |
+| `result.total_return_pct` | float | Account return % using the replay starting balance |
+| `result.sharpe_ratio`     | float | Sharpe ratio                 |
+| `result.max_drawdown_pct` | float | Max drawdown %               |
+| `result.win_rate`         | float | Win rate fraction (0.0-1.0)  |
+| `result.total_trades`     | int   | Total closed position count  |
+| `result.profit_factor`    | float | Profit factor                |
+| `result.summary`          | dict  | Stable normalized account-level summary |
+| `result.raw`              | dict  | Full Nautilus-derived output |
+
+
+`result.raw` keeps these top-level sections:
+
+- `summary`
+- `stats`
+- `reports`
+- `config`
+
+## Multi-Instrument Replays
+
+Use `instruments:` when the strategy needs multiple instrument definitions.
+
+Provide one OHLCV DataFrame per declared instrument ID or symbol:
+
+```python
+result = backtest.run(
+    ohlcv_data={
+        "BTCUSDT.BINANCE": btc_df,
+        "ETHUSDT.BINANCE": eth_df,
+    },
+    spec=runtime.backtest_spec,
+)
+```
+
+The engine does not synthesize cross-instrument logic for you. Multi-instrument
+behavior belongs in the author's Nautilus strategy code.
+
+## Zero-Trade Diagnostics
+
+If `result.total_trades == 0`, common causes are:
+
+1. bars were filtered out by `execution.start` / `execution.end`
+2. the strategy never subscribed to the declared `bar_type`
+3. instrument IDs in strategy config do not match the spec
+4. order sizing is invalid for the declared increment / lot size
+
+Inspect:
+
+- `result.raw["config"]`
+- `result.raw["reports"]["orders"]`
+- `result.raw["reports"]["fills"]`
+- `result.raw["reports"]["positions"]`
+
+## Chart Generation
+
+```python
+chart_path = backtest.generate_chart(result)
+```
+
+The managed chart renderer writes a PNG summary to `/workspace/output/`.
+
+Current chart includes:
+
+- equity curve when available
+- normalized metrics when no curve is available
+- key summary values