Metadata-Version: 2.4
Name: fasterfoodsstack
Version: 0.1.0
Summary: SDK for writing FasterFoods recommendation algorithms
License: MIT
Project-URL: Homepage, https://github.com/RitvikJoshi97/fasterfoodsstack
Keywords: fasterfoodsstack,fasterfoods,nutrition,recommendation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# fasterfoodsstack (Python)

SDK for writing FasterFoods recommendation algorithms in Python.

## Install

```bash
pip install fasterfoodsstack
```

Or from source:
```bash
cd python/
pip install -e .
```

## Quickstart

```python
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)

| Attribute | Type | Description |
|-----------|------|-------------|
| `ffs.user.profile.dietary_flags` | `list[str]` | e.g. `["vegetarian", "gluten-free"]` |
| `ffs.user.meals.last` | `Meal \| None` | Most recently logged meal |
| `ffs.user.meals.history(days=7)` | `list[Meal]` | Meals in the last N days |
| `ffs.user.meals.favorites` | `list[Meal]` | User's favourite meals |
| `ffs.user.goals.calories` | `int` | Daily calorie target |
| `ffs.user.goals.protein_g` | `float` | Daily protein target (grams) |
| `ffs.user.goals.carbs_g` | `float` | Daily carbs target (grams) |
| `ffs.user.goals.fat_g` | `float` | Daily fat target (grams) |
| `ffs.user.goals.goal_type` | `str` | `"lose_weight"` \| `"maintain"` \| `"gain_muscle"` |

### `ffs.recommend`

```python
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.

```python
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.
