SDK Generations¶
Two generations of the Almanak SDK run on the platform side by side. Both are published under the
distribution name almanak; the major version tells them apart.
SDK v2 (almanak 2.x) |
SDK v3 (almanak 3.x) |
|
|---|---|---|
| Repository layout | strategy.py, config.json, pyproject.toml with [tool.almanak.run] |
strategy.py, config.yaml, optional backtest.yaml / backtest-economic.yaml |
| Strategy contract | IntentStrategy with intents such as Swap, LP or Borrow |
Hook functions (decide, on_outcome) over explicit connector declarations |
| Configuration | config.json, overridable per deployment |
config.yaml, validated against the SDK schema; the platform passes it through unchanged |
| Permissions | almanak strat permissions exports a Zodiac Roles manifest before deployment |
The running deployment exports owner transactions; the deployment waits in Action required until they are executed |
| Dashboard | Streamlit page served by the deployment | JSON dashboard evaluated inside the deployment pod and rendered on the deployment page |
| Backtests | Platform backtest runner with start and end dates | backtest.yaml or backtest-economic.yaml from the repository, run by the same platform runner |
| Availability | Production | Staging preview |
Which generation is my strategy?¶
The platform classifies a repository when it is linked and records the generation on the strategy.
The resolved almanak version decides: a lockfile or pyproject.toml that resolves to almanak
3.x makes the strategy SDK v3, and the repository must then contain strategy.py and config.yaml.
Anything that resolves below 3.0 keeps the SDK v2 rules described in Deploy.
The Strategy Library shows the generation on every strategy and deployment. A strategy never changes generation in place: to move to SDK v3, link a repository authored for it.
What the platform does with each generation¶
- Deploy: the deploy flow, the deployment controls and the dashboard are chosen by the strategy's generation. A v3 strategy cannot be deployed through the v2 path and the other way round; the platform refuses the mismatch instead of guessing.
- Backtest: v2 runs take a date window and a strategy configuration; v3 runs take one of the repository's backtest files (or an edited copy of it) and validate it inside the runner.
- Almanak Code: a session attached to a v3 strategy uses the SDK v3 assistant and validates the
workspace with
almanak check. Sessions without a repository, and sessions attached to v2 strategies, use SDK v2. - Supported protocols: the supported protocols list names the generations that ship each protocol. A protocol listed for v3 only cannot be deployed with a v2 strategy.
Staging preview¶
SDK v3 is available on staging to invited accounts, selected with the SDK v2 / v3 switch in the sidebar. The switch is a view preference: it filters the library and opens the v3 deploy and backtest pages, but the stored generation of a strategy always decides which path runs. Production runs SDK v2 only until the preview completes.