fasterfoodsstack (Python)

SDK for writing FasterFoods recommendation algorithms in Python.

Install

pip install fasterfoodsstack

Or from source:

cd python/
pip install -e .

Quickstart

import fasterfoodsstack as ffs
from fasterfoodsstack import run_local

# Set your dev API key once (or use the FASTERFOODS_API_KEY env var)
ffs.configure(api_key="ffs-dev-...")

# Write your recommendation algorithm
def get_meal_recommendation(user):
    remaining = user.goals.calories - (user.meals.last.calories if user.meals.last else 0)

    if user.goals.goal_type == "gain_muscle":
        return ffs.recommend.meal(
            name="Grilled Chicken Bowl",
            reason=f"{remaining} kcal remaining — prioritising protein for muscle gain",
            calories=720,
            protein_g=60.0,
            tags=["high-protein", "meal-prep"],
        )

    return ffs.recommend.meal(
        name="Tuna & Quinoa Salad",
        reason=f"{remaining} kcal remaining today",
        calories=480,
        protein_g=42.0,
        tags=["high-protein", "low-carb"],
    )

# Fetch a pre-seeded test profile from the dev environment and run locally
ctx = ffs.dummy.athlete()
result = run_local(get_meal_recommendation, ctx)
# -> prints timing, validates return type, prints result fields

# Available profiles: athlete(), weight_loss(), starter(), family()
ctx = ffs.dummy.weight_loss()
result = run_local(get_meal_recommendation, ctx)

API reference

ffs.user (runtime, injected by platform)

ffs.recommend

ffs.recommend.meal(
    name: str,
    reason: str,
    calories: int,
    protein_g: float,
    tags: list[str] = [],
) -> MealRecommendation

ffs.recommend.workout(
    type: str,          # "strength" | "cardio" | "flexibility" | "rest"
    duration_minutes: int,
    reason: str,
) -> WorkoutRecommendation

ffs.dummy

Fetches pre-seeded test user contexts from the FasterFoods dev environment. Each call makes an authenticated API request and returns a user context with the same shape as the runtime user namespace.

ctx = ffs.dummy.athlete()      # high-calorie, gain_muscle
ctx = ffs.dummy.weight_loss()  # caloric deficit, gluten-free
ctx = ffs.dummy.starter()      # balanced beginner, maintain
ctx = ffs.dummy.family()       # vegetarian, maintain

ffs.configure(api_key, base_url=None)

Sets the API key for all SDK calls. Call once at startup, or set FASTERFOODS_API_KEY in your environment instead.

run_local(fn, context)

Runs your function with a fetched user context, prints timing and the result, validates the return type.