Examples and recipes
Examples are editable contracts. Use them to learn a pattern, then test the assumptions required by your own scenario.
| Example | What to study |
|---|---|
| Weekly inventory | Small complete contract with hand-calculated outputs |
| Auto parts store | SKU tables, seasonality, substitution, demand and replenishment |
| Coffee market | Households, pricing and repeated purchases |
| Phone reseller | A larger business model to inspect and adapt |
| Trade negotiation | Several participants making interdependent decisions |
Develop from an editable source checkout
Normal users should install from PyPI. Clone GitHub only when changing the SDK itself or running repository examples against an editable checkout.
git clone https://github.com/Fareground/environments-sdk.git
cd environments-sdk
git checkout v0.7.1
python -m pip install -e .
fg-env check examples/contracts/weekly_inventory.json
fg-env run examples/contracts/weekly_inventory.json --agent retailer=policy:steady --seed 7
Keep data directories beside contracts that refer to CSVs or assets. Copying only a JSON file may omit required inputs.
Find a reusable primitive
Business modeling maps requirements to contract features. Recipes shows composition patterns. The full reference covers exact syntax and defaults.
Names, versions and migration
Public names
| Surface | Current name |
|---|---|
| Product | environments-sdk |
| GitHub repository | Fareground/environments-sdk |
| Python distribution | fg-env |
| Python import | fg_env |
| CLI | fg-env |
For the current contract SDK, the repository and product rename does not require changing fg_env imports. Releases from 0.3 onward use the fg-env distribution. Upgrade in a fresh virtual environment and verify your scenario tests. If your checkout still uses a legacy repository URL, update its remote:
git remote set-url origin https://github.com/Fareground/environments-sdk.git
Install or upgrade the current release from PyPI:
python -m pip install --upgrade fg-env
For a reproducible deployment, pin fg-env==0.7.1 after validating your scenario.
Contract API versus legacy templates
New environments should use JSON contracts through fg_env.check, fg_env.load and fg_env.run. The older template engine remains under fg_env.legacy, with CLI commands under fg-env legacy. A legacy Python template is not automatically a JSON contract; migrating it requires mapping its rules and testing equivalent behavior.
Release discipline
These pages describe 0.7.1. Pin the SDK version for deployed scenarios and store it with each run. Before an upgrade, run scenario acceptance cases, compare outputs, and test saved-state restoration. Do not assume snapshots are portable across all versions.
See the repository changelog for release changes. Publishing a package and deploying a platform are separate operations; a new documentation page alone does not establish which version a host is running.