@bitget-ai/getagent-skill 0.2.1

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

@@ -0,0 +1,126 @@
+# Uscongress 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
+- [`uscongress.bill_info`](#uscongressbill-info)
+- [`uscongress.bill_text`](#uscongressbill-text)
+- [`uscongress.bill_text_urls`](#uscongressbill-text-urls)
+- [`uscongress.bills`](#uscongressbills)
+
+## Endpoint reference
+
+### `uscongress.bill_info`
+
+```python
+data.uscongress.bill_info(bill_url=None, provider='congress_gov')
+```
+
+Summary: Bill Info
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `uscongress.bill_info` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/uscongress/bill_info` |
+| Default provider | `congress_gov` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `bill_url` | `no` | `string | null` | `-` | Enter a base URL of a bill (e.g., 'https://api.congress.gov/v3/bill/119/s/1947?format=json'). Alternatively, you can enter a bill number (e.g., '119/s/1947'). (provider: congress_gov) |
+| `provider` | `no` | `string` | `congress_gov` | - |
+
+---
+
+### `uscongress.bill_text`
+
+```python
+data.uscongress.bill_text(provider='congress_gov', body=...)
+```
+
+Summary: Bill Text
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `uscongress.bill_text` |
+| HTTP | `POST` |
+| Path | `/inner/v1/agent-data/uscongress/bill_text` |
+| Default provider | `congress_gov` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `provider` | `no` | `string` | `congress_gov` | - |
+| `body` | `no` | `string | array | object | null` | `-` | List of direct bill URLs to download. Multiple comma separated items allowed. (provider: congress_gov) |
+
+---
+
+### `uscongress.bill_text_urls`
+
+```python
+data.uscongress.bill_text_urls(bill_url=..., is_workspace=False, provider='congress_gov')
+```
+
+Summary: Bill Text Urls
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `uscongress.bill_text_urls` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/uscongress/bill_text_urls` |
+| Default provider | `congress_gov` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `bill_url` | `yes` | `string` | `-` | - |
+| `is_workspace` | `no` | `boolean` | `false` | - |
+| `provider` | `no` | `string` | `congress_gov` | - |
+
+---
+
+### `uscongress.bills`
+
+```python
+data.uscongress.bills(congress=None, bill_type=None, start_date=None, end_date=None, limit=None, offset=None, sort_by='desc', provider='congress_gov')
+```
+
+Summary: Bills
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `uscongress.bills` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/uscongress/bills` |
+| Default provider | `congress_gov` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `congress` | `no` | `integer | null` | `-` | Congress number (e.g., 118 for the 118th Congress). The 103rd Congress started in 1993, which is the earliest date supporting full text versions. Each Congress spans two years, starting in odd-numbered years. (provider: congress_gov) |
+| `bill_type` | `no` | `string | null` | `-` | Bill type (e.g., "hr" for House bills). Must be one of: hr, s, hjres, sjres, hconres, sconres, hres, sres. Bills ----- A bill is the form used for most legislation, whether permanent or temporary, general or special, public or private. A bill originating in the House of Representatives is designated by the letters “H.R.”, signifying “House of Representatives”, followed by a number that it retains throughout all its parliamentary stages. Bills are presented to the President for action when approved in identical form by both the House of Representatives and the Senate. Joint Resolutions ----------------- Joint resolutions may originate either in the House of Representatives or in the Senate. There is little practical difference between a bill and a joint resolution. Both are subject to the same procedure, except for a joint resolution proposing an amendment to the Constitution. On approval of such a resolution by two-thirds of both the House and Senate, it is sent directly to the Administrator of General Services for submission to the individual states for ratification. It is not presented to the President for approval. A joint resolution originating in the House of Representatives is designated “H.J.Res.” followed by its individual number. Joint resolutions become law in the same manner as bills. Concurrent Resolutions ---------------------- Matters affecting the operations of both the House of Representatives and Senate are usually initiated by means of concurrent resolutions. A concurrent resolution originating in the House of Representatives is designated “H.Con.Res.” followed by its individual number. On approval by both the House of Representatives and Senate, they are signed by the Clerk of the House and the Secretary of the Senate. They are not presented to the President for action. Simple Resolutions ------------------ A matter concerning the operation of either the House of Representatives or Senate alone is initiated by a simple resolution. A resolution affecting the House of Representatives is designated “H.Res.” followed by its number. They are not presented to the President for action. (provider: congress_gov) |
+| `start_date` | `no` | `string | null` | `-` | Start date of the data, in YYYY-MM-DD format. Filters bills by the last updated date. (provider: congress_gov) |
+| `end_date` | `no` | `string | null` | `-` | End date of the data, in YYYY-MM-DD format. Filters bills by the last updated date. (provider: congress_gov) |
+| `limit` | `no` | `integer | null` | `-` | The number of data entries to return. When None, default sets to 100 (max 250). Set to 0 for no limit (must be used with 'bill_type' and 'congress'). Setting to 0 will nullify the start_date, end_date, and offset parameters. (provider: congress_gov) |
+| `offset` | `no` | `integer | null` | `-` | The starting record returned. 0 is the first record. (provider: congress_gov) |
+| `sort_by` | `no` | `string` | `desc` | Sort by update date. Default is latest first. (provider: congress_gov) |
+| `provider` | `no` | `string` | `congress_gov` | - |

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

@@ -0,0 +1,68 @@
+# Web_Search 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
+- [`web_search.news`](#web-searchnews)
+- [`web_search.web`](#web-searchweb)
+
+## Endpoint reference
+
+### `web_search.news`
+
+```python
+data.web_search.news(query=..., max_results=10, page=1, provider='bravesearch')
+```
+
+Summary: News
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `web_search.news` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/web_search/news` |
+| Default provider | `bravesearch` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `query` | `yes` | `string` | `-` | Search query string. |
+| `max_results` | `no` | `integer` | `10` | Maximum number of news results to return. |
+| `page` | `no` | `integer` | `1` | Page number for pagination, starting at 1. |
+| `provider` | `no` | `string` | `bravesearch` | - |
+
+---
+
+### `web_search.web`
+
+```python
+data.web_search.web(query=..., max_results=10, page=1, backend='auto', provider=...)
+```
+
+Summary: Web
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `web_search.web` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/web_search/web` |
+| Default provider | - |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `query` | `yes` | `string` | `-` | Search query string. |
+| `max_results` | `no` | `integer` | `10` | Maximum number of results to return. |
+| `page` | `no` | `integer` | `1` | Page number for pagination, starting at 1. |
+| `backend` | `no` | `string` | `auto` | enum: auto, duckduckgo, google, bing, brave, yandex, yahoo, wikipedia, grokipedia, mojeek Search engine backend. 'auto' queries multiple engines with automatic fallback for resilience. (provider: ddgs) |
+| `provider` | `yes` | `string` | `-` | enum: bravesearch, ddgs |

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

@@ -0,0 +1,97 @@
+# Wikipedia 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
+- [`wikipedia.content`](#wikipediacontent)
+- [`wikipedia.search`](#wikipediasearch)
+- [`wikipedia.summary`](#wikipediasummary)
+
+## Endpoint reference
+
+### `wikipedia.content`
+
+```python
+data.wikipedia.content(title=None, lang='en', intro_only=False, provider='wikipedia')
+```
+
+Summary: Content
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `wikipedia.content` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/wikipedia/content` |
+| Default provider | `wikipedia` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `title` | `no` | `string | null` | `-` | Wikipedia article title to retrieve. (provider: wikipedia) |
+| `lang` | `no` | `string` | `en` | Wikipedia language edition. (provider: wikipedia) |
+| `intro_only` | `no` | `boolean` | `false` | Return only the introductory section instead of the full article. (provider: wikipedia) |
+| `provider` | `no` | `string` | `wikipedia` | - |
+
+---
+
+### `wikipedia.search`
+
+```python
+data.wikipedia.search(query=None, max_results=10, page=1, lang='en', provider='wikipedia')
+```
+
+Summary: Search
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `wikipedia.search` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/wikipedia/search` |
+| Default provider | `wikipedia` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `query` | `no` | `string | null` | `-` | Search query string. (provider: wikipedia) |
+| `max_results` | `no` | `integer` | `10` | Maximum number of results. (provider: wikipedia) |
+| `page` | `no` | `integer` | `1` | Page number, starting at 1. (provider: wikipedia) |
+| `lang` | `no` | `string` | `en` | Wikipedia language edition. (provider: wikipedia) |
+| `provider` | `no` | `string` | `wikipedia` | - |
+
+---
+
+### `wikipedia.summary`
+
+```python
+data.wikipedia.summary(title=None, lang='en', provider='wikipedia')
+```
+
+Summary: Summary
+
+| Field | Value |
+|---|---|
+| Endpoint ID | `wikipedia.summary` |
+| HTTP | `GET` |
+| Path | `/inner/v1/agent-data/wikipedia/summary` |
+| Default provider | `wikipedia` |
+| SDK | `supported` |
+| Host | `supported` |
+| Notes | - |
+
+#### Query parameters
+
+| Param | Required | Type | Default | Notes |
+|---|---|---|---|---|
+| `title` | `no` | `string | null` | `-` | Wikipedia article title to retrieve. (provider: wikipedia) |
+| `lang` | `no` | `string` | `en` | Wikipedia language edition. (provider: wikipedia) |
+| `provider` | `no` | `string` | `wikipedia` | - |

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

@@ -0,0 +1,117 @@
+# `getagent.llm`
+
+Author-facing bounded LLM surface for live-only Playbooks.
+
+## When to use
+
+Use `getagent.llm` when the strategy depends on runner-managed model reasoning
+that cannot be fairly replayed from historical market data alone.
+
+Typical fit:
+
+- `runtime_profile: llm_bounded`
+- `backtest_support: none`
+- live/paper evidence instead of historical backtest claims
+
+Do **not** use `getagent.llm` for replayable logic that should stay in
+`getagent.backtest`.
+
+## Public API
+
+### Availability
+
+- `llm.is_available() -> bool`
+  - Returns whether the current sandbox run injected bounded LLM access
+  - `False` in deterministic runs
+
+### Calls
+
+- `llm.complete(prompt, *, system=None, max_tokens=None, temperature=None) -> LLMResult`
+- `llm.chat(messages, *, system=None, max_tokens=None, temperature=None) -> LLMResult`
+
+`messages` accepts either:
+
+- `llm.LLMMessage(role="user", content="...")`
+- plain dicts like `{"role": "user", "content": "..."}`
+
+### Result shape
+
+`LLMResult` exposes:
+
+- `content`
+- `model`
+- `request_id`
+- `finish_reason`
+- `usage`
+- `raw`
+
+`raw` currently carries lightweight provider metadata such as reasoning text or
+estimated cost when available.
+
+## Runtime boundaries
+
+The bounded runtime is intentionally narrow:
+
+- one runner-managed model only
+- no free model switching from Playbook code
+- no tool calls
+- no direct `httpx` / `requests` / `litellm` usage from Playbook source
+- fixed limits for:
+  - calls per run
+  - prompt characters
+  - output tokens
+  - timeout
+
+If a request exceeds those limits, `getagent.llm` raises a typed runtime error
+instead of silently falling back.
+
+## Errors
+
+The module raises explicit `RuntimeError` subclasses:
+
+- `LLMRuntimeUnavailableError` — this run is not `llm_bounded`
+- `LLMConfigurationError` — runner-side LLM config is missing or invalid
+- `LLMInputError` — caller input is malformed
+- `LLMBudgetExceededError` — bounded runtime budget exceeded
+- `LLMError` — upstream/provider call failed
+
+## Example
+
+```python
+from getagent import llm, runtime
+
+if not llm.is_available():
+    raise RuntimeError("This playbook requires runtime_profile=llm_bounded")
+
+summary = llm.complete(
+    "Summarize today's macro risk for BTC in 3 sentences.",
+    system="You are a cautious crypto macro analyst.",
+    max_tokens=300,
+)
+
+runtime.emit_signal(
+    action="watch",
+    symbol="BTCUSDT",
+    confidence=0.55,
+    meta={
+        "llm_summary": summary.content,
+        "llm_model": summary.model,
+    },
+)
+```
+
+## Hard rules
+
+- Keep LLM outputs as bounded inputs into trading logic, not as an open-ended
+  agent loop
+- Do not claim historical replayability for `llm_bounded` strategies
+- Do not read `GETAGENT_LLM_*` env vars directly unless debugging a runtime issue
+- Do not import internal implementation modules such as `getall`, `litellm`, or
+  `httpx`
+
+## Related docs
+
+- [`../../package-schema.md`](../../package-schema.md)
+- [`../../sandbox-runtime.md`](../../sandbox-runtime.md)
+- [`../../api/publish.md`](../../api/publish.md)
+- [`../../api/enable.md`](../../api/enable.md)

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

@@ -0,0 +1,195 @@
+# `getagent.runtime`
+
+Author-facing runtime protocol for Playbooks.
+
+## When to use
+
+Use `getagent.runtime` whenever Playbook code needs runner-injected context or
+needs to emit managed signal output back to the platform.
+
+Typical fit:
+
+- read package metadata from `manifest.yaml`
+- read the explicit Nautilus replay spec from `backtest.yaml`
+- branch between historical and live execution
+- access the current run ID
+- emit one or more signals in the platform format
+
+`getagent.runtime` is the boundary between strategy code and the managed runner.
+It is not a planner, memory system, trading client, or persistence layer.
+
+## Public API
+
+### Context
+
+- `runtime.manifest`
+  - lazy mapping backed by `/workspace/manifest.yaml`
+  - use for package fields such as symbols, schedule, metadata, and `strategy_config`
+
+- `runtime.backtest_spec`
+  - lazy mapping backed by `/workspace/backtest.yaml`
+  - only meaningful when `manifest.yaml` sets `backtest_support: full`
+  - carries the explicit Nautilus replay spec: `venue`, `instrument` or
+    `instruments`, `strategy`, optional `execution`, and optional
+    `data_requirements`
+
+- `runtime.run_id`
+  - runner-injected identifier for the current execution
+
+- `runtime.evaluation_mode`
+  - runner-injected execution mode
+  - currently `"historical"` for `POST /api/v1/playbook/run`
+  - currently `"live"` for follow/subscription schedule executions
+
+- `runtime.is_historical() -> bool`
+  - true when this execution should use historical/backtest semantics
+
+- `runtime.is_live() -> bool`
+  - true when this execution should use live market/trading semantics
+
+- `runtime.execution_mode() -> str`
+  - returns the injected subscription mode, currently `"signal_only"` or
+    `"follow_trade"`
+
+- `runtime.is_signal_only() -> bool`
+  - true when live execution should emit signals but never place orders
+
+- `runtime.is_follow_trade() -> bool`
+  - true when live execution may place orders after emitting the signal
+
+- `runtime.is_actionable_signal(signal_or_action) -> bool`
+  - true when the signal action is not `watch`, `hold`, `noop`, `none`, or empty
+
+- `runtime.should_follow_trade(signal_or_action) -> bool`
+  - true only when the current subscription is `"follow_trade"` and the signal
+    action is actionable
+
+- `runtime.emit_signal_or_follow(..., execute_trade=None) -> FollowTradeResult`
+  - emits a managed signal and automatically decides whether to call the
+    `execute_trade` callback based on `execution_mode` and signal action
+
+### Output
+
+- `runtime.emit_signal(action, symbol="", confidence=0.0, metrics=None, meta=None) -> SignalPayload`
+- `runtime.get_emitted_signals() -> list[SignalPayload]`
+
+`emit_signal(...)` does three things:
+
+1. returns a typed `SignalPayload`
+2. prints one JSON record to stdout
+3. appends the record to `/workspace/output/signal.json`
+
+## Historical / Live Split
+
+Do not put `run_mode` in `manifest.yaml`. A package is immutable and should run
+both modes from the same uploaded version. Branch on `runtime.evaluation_mode` in
+`src/main.py`:
+
+```python
+from getagent import runtime
+from . import main_backtest, main_live
+
+if runtime.is_historical():
+    main_backtest.run()
+elif runtime.is_live():
+    main_live.run()
+else:
+    raise ValueError(f"unsupported evaluation_mode={runtime.evaluation_mode!r}")
+```
+
+Keep shared feature engineering in a neutral module like `features.py`.
+`main_backtest.py` must not import live trading code or call `getagent.trade`.
+`main_live.py` may call `getagent.trade` and can place real orders when the
+current subscription is in follow-trade mode.
+
+Live code must separate decision output from trade execution:
+
+```python
+from getagent import runtime, trade
+
+
+def run() -> None:
+    decision = build_live_decision()
+
+    runtime.emit_signal_or_follow(
+        action=decision.action,
+        symbol=decision.symbol,
+        confidence=decision.confidence,
+        metrics=decision.metrics,
+        meta=decision.meta,
+        execute_trade=lambda: execute_trade(decision),
+    )
+```
+
+Signal-only runs should complete after emitting the signal. Do not call
+`trade.contract.*` or `trade.spot.*` mutation APIs and rely on the SDK safety
+guard to fail.
+
+## Output Contract
+
+Use `runtime.emit_signal(...)` for strategy conclusions that should be persisted
+as managed Playbook output.
+
+Arguments:
+
+- `action` — signal action such as `long`, `short`, `close`, `hold`, or `watch`
+- `symbol` — target instrument, usually something like `BTCUSDT`
+- `confidence` — float confidence score
+- `metrics` — structured numeric summary
+- `meta` — extra non-core context for downstream inspection
+
+The runner collects `/workspace/output/signal.json` automatically. Do not write
+that file yourself unless you are debugging the runtime contract.
+
+If a live run emits an actionable trade signal and then emits a `watch` summary,
+the platform treats the last actionable signal as primary. Use `watch` for final
+summary context, not as a replacement for `long`, `short`, or `close`.
+
+## Example
+
+```python
+from getagent import runtime
+
+primary_symbol = runtime.manifest.get("trading_symbols", ["BTCUSDT"])[0]
+config = runtime.manifest.get("strategy_config", {})
+
+if runtime.is_historical():
+    runtime.emit_signal(
+        action="watch",
+        symbol=primary_symbol,
+        confidence=0.5,
+        metrics={"mode": "historical", "lookback_hours": config.get("lookback_hours", 360)},
+        meta={"run_id": runtime.run_id},
+    )
+else:
+    runtime.emit_signal(
+        action="long",
+        symbol=primary_symbol,
+        confidence=0.72,
+        metrics={"mode": "live"},
+        meta={"run_id": runtime.run_id},
+    )
+```
+
+## Hard Rules
+
+- Treat `runtime.manifest` as the source of truth for package contract fields.
+- Read every user-editable strategy parameter from
+  `runtime.manifest.get("strategy_config", {})`; do not hardcode values that
+  appear in `user_config_schema`.
+- Treat `runtime.backtest_spec` as optional; do not assume it exists.
+- Use `runtime.evaluation_mode` / `runtime.is_historical()` / `runtime.is_live()` for mode routing.
+- Prefer `runtime.emit_signal_or_follow(...)` for live signal-only vs
+  follow-trade routing.
+- Use `runtime.emit_signal(...)` instead of inventing your own signal schema.
+- Emit the signal before placing follow-trade orders. Signal-only runs must
+  return after `emit_signal(...)`.
+- Do not expect `runtime` to expose trading, data, or LLM clients.
+- Do not use `runtime` as a hidden persistence layer beyond emitted signals.
+
+## Related Docs
+
+- [`../../package-schema.md`](../../package-schema.md)
+- [`../../sandbox-runtime.md`](../../sandbox-runtime.md)
+- [`../../backtest-engine.md`](../../backtest-engine.md)
+- [`../llm/catalog.md`](../llm/catalog.md)

package/skills/getagent/references/sdk/trade/account.md

@@ -0,0 +1,61 @@
+# Trade Account Reference
+
+Account queries and internal balance transfers.
+
+These signatures are written against the `getagent.trade` public contract.
+Runner-managed identity kwargs (`user_id`, `channel`, `trace_id`) are
+intentionally omitted from the author-facing signatures below.
+
+## Contents
+- [`trade.account.subaccount_exists`](#tradeaccountsubaccount-exists)
+- [`trade.account.total_value`](#tradeaccounttotal-value)
+- [`trade.account.transfer`](#tradeaccounttransfer)
+
+## Method reference
+
+### `trade.account.subaccount_exists`
+
+```python
+trade.account.subaccount_exists()
+```
+
+Summary: Return True when the trade-proxy subaccount for ``user_id`` exists.
+
+No author-supplied parameters.
+
+Returns: `bool`
+
+---
+
+### `trade.account.total_value`
+
+```python
+trade.account.total_value()
+```
+
+Summary: Query the unified total-asset snapshot for the current user.
+
+No author-supplied parameters.
+
+Returns: `TotalValueResult`
+
+---
+
+### `trade.account.transfer`
+
+```python
+trade.account.transfer(from_type, to_type, amount, coin)
+```
+
+Summary: Move funds between ``spot`` and ``usdt_futures`` sub-wallets.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `from_type` | `yes` | `AccountTypeLiteral` | - |
+| `to_type` | `yes` | `AccountTypeLiteral` | - |
+| `amount` | `yes` | `Any` | - |
+| `coin` | `yes` | `str` | - |
+
+Returns: `TransferResult`
+
+---