What belongs in an example project
Keep configuration, API calls, result validation and presentation separate. Supply addresses and credentials through environment configuration and specify dependency and runtime versions. Show successful and failed results so users can assess both execution and business correctness.
If your release includes an official SDK, follow its version-specific installation and authentication instructions. Otherwise, write the client against the agreed API contract. Confirm package names with the provider and keep personal credentials out of the repository.
Start with a fully local synthetic example
The Python standard-library example below filters by status and then totals the selected rows. It runs locally without calling AI-Soda Brain or connecting to a database. Use it as a starting point for testing a metric definition. The expected total is 200.00.
from decimal import Decimal
# Synthetic records for a local calculation. No AI-Soda Brain SDK call is made.
orders = [
{"region": "A", "status": "confirmed", "amount": "120.00"},
{"region": "B", "status": "confirmed", "amount": "80.00"},
{"region": "A", "status": "cancelled", "amount": "30.00"},
]
total = sum(
(Decimal(row["amount"]) for row in orders
if row["status"] == "confirmed"),
Decimal("0.00"),
)
assert total == Decimal("200.00")
print(total)Add the service call
- Keep the local baseline data and expected output so the calculation can be exercised independently.
- Implement the call according to the actual contract and configure timeouts and cancellation in the test environment.
- Convert the returned values to an explicit data structure that distinguishes completed, failed and partial results.
- Check that logs omit credentials, full private questions and unnecessary record-level details.
Include failure cases in the example
Cover empty results, type mismatches, unknown fields, timeouts and insufficient permissions at a minimum. Give users a next diagnostic step alongside the error. Rerun these cases after dependency or service upgrades to identify which layer changed.
Include boundary cases for amounts, missing values and status fields. Distinguish a missing value from a numeric zero. Automatically filling gaps in the display can hide a data-quality issue or a protocol change.
