Tengo Hambre: Recipe Suggestions from Expiring Items

FridgeRadar’s recipe system does more than store cooking instructions — it actively helps you reduce food waste. The Tengo Hambre (“I’m hungry”) engine scans your household’s pantry, identifies ingredients that are close to expiry, and ranks every public recipe by how many of those ingredients you already have on hand. The result is a personalised suggestion list that prioritises meals you can cook right now using items that would otherwise go bad.

The Recipe Data Model

Recipes are created with RecetaCreate and returned as RecetaDetalleResponse, which extends the base response with full tag and ingredient lists.

Core Fields (`RecetaCreate`)

Field	Type	Description
`nombre`	`str`	Recipe name
`descripcion`	`str \| null`	Short summary of the dish
`instrucciones`	`str \| null`	Step-by-step cooking instructions
`tiempo_preparacion`	`int \| null`	Preparation time in minutes
`dificultad`	`str`	`"facil"`, `"media"`, or `"dificil"`
`porciones`	`int \| null`	Number of servings
`imagen`	`str \| null`	URL to a cover image
`calorias`	`int \| null`	Calories per serving
`es_publica`	`bool`	Whether the recipe is visible to all users (default `true`)
`tags`	`list[int]`	List of tag IDs to attach
`ingredientes`	`list[RecetaIngredienteCreate]`	List of required ingredients

Ingredient Entry (`RecetaIngredienteCreate`)

Field	Type	Description
`id_producto`	`int`	Product catalogue reference
`cantidad`	`float \| null`	How much is needed
`unidad_medida`	`str`	Unit (default `"unidad"`)
`obligatorio`	`bool`	Whether this ingredient is mandatory (default `true`)
`nota`	`str \| null`	Preparation note (e.g. “diced finely”)

Creating a Recipe

POST /api/v1/recetas/
Authorization: Bearer <token>
Content-Type: application/json

{
  "nombre": "Tortilla de papas",
  "descripcion": "Clásica tortilla española con papas y cebolla.",
  "instrucciones": "1. Pelar y cortar papas...",
  "tiempo_preparacion": 30,
  "dificultad": "media",
  "porciones": 4,
  "calorias": 320,
  "es_publica": true,
  "tags": [2, 5],
  "ingredientes": [
    { "id_producto": 10, "cantidad": 3, "unidad_medida": "unidad", "obligatorio": true },
    { "id_producto": 22, "cantidad": 1, "unidad_medida": "unidad", "obligatorio": false, "nota": "opcional" }
  ]
}

Detail Response (`RecetaDetalleResponse`)

RecetaDetalleResponse extends the base RecetaResponse with two populated lists:

{
  "id_receta": 14,
  "id_usuario_creador": 3,
  "nombre": "Tortilla de papas",
  "descripcion": "Clásica tortilla española con papas y cebolla.",
  "tiempo_preparacion": 30,
  "dificultad": "media",
  "porciones": 4,
  "calorias": 320,
  "es_publica": true,
  "fecha_creacion": "2024-10-05T09:00:00",
  "tags": [
    { "id_tag": 2, "nombre": "Vegetariano", "color": "#4CAF50" }
  ],
  "ingredientes": [
    {
      "id_receta_ingrediente": 31,
      "id_receta": 14,
      "id_producto": 10,
      "cantidad": 3.0,
      "unidad_medida": "unidad",
      "obligatorio": true,
      "nota": null
    }
  ]
}

Recipe Tags

Tags are lightweight labels (id_tag, nombre, color) used to categorise recipes. Create and list tags through dedicated endpoints.

Method	Path	Description
`POST`	`/api/v1/recetas/tags`	Create a new tag
`GET`	`/api/v1/recetas/tags`	List all available tags

POST /api/v1/recetas/tags
Authorization: Bearer <token>
Content-Type: application/json

{
  "nombre": "Sin gluten",
  "color": "#FF9800"
}

{
  "id_tag": 7,
  "nombre": "Sin gluten",
  "color": "#FF9800"
}

Recipe Favourites

Users can bookmark any recipe as a personal favourite. Favourites are per-user, not per-household.

Method	Path	Description
`POST`	`/api/v1/recetas/{id_receta}/favorito`	Add a recipe to your favourites
`DELETE`	`/api/v1/recetas/{id_receta}/favorito`	Remove a recipe from your favourites
`GET`	`/api/v1/recetas/favoritos/mios`	List all your favourited recipes

The Tengo Hambre Engine

Calling GET /api/v1/tengo-hambre/{id_hogar} runs the suggestion engine for the specified household. The engine:

Loads all public recipes

Fetches every recipe where es_publica = true, along with its full ingredient list.

Reads the household inventory

Loads all inventory items for id_hogar and groups them by id_producto.

Filters by freshness (solo_criticos)

When solo_criticos = true (the default), only ingredients whose pantry items are in "amarillo" or "rojo" state are counted as available. When false, any stocked ingredient counts.

Calculates porcentaje_match

For each recipe: porcentaje_match = (ingredients_found / total_ingredients) × 100, floored to two decimal places. Only recipes with ≥ 70 % match are included.

Sorts and trims the list

Results are sorted so recipes that use critical (usa_criticos = true) items appear first, then by porcentaje_match descending. The list is trimmed to limite results.

Persists suggestions

The suggestions are saved to the SugerenciaReceta table for the user/household pair (replacing any previous run) before being returned.

Query Parameters

Parameter	Type	Default	Description
`solo_criticos`	`bool`	`true`	Only match ingredients in `amarillo` or `rojo` state
`limite`	`int`	`10`	Maximum number of suggestions to return

Example Request

GET /api/v1/tengo-hambre/1?solo_criticos=true&limite=5
Authorization: Bearer <token>

Suggestion Response (`SugerenciaResponse`)

Field	Type	Description
`id_receta`	`int`	Recipe identifier
`nombre`	`str`	Recipe name
`descripcion`	`str \| null`	Short description
`tiempo_preparacion`	`int \| null`	Prep time in minutes
`dificultad`	`str`	Difficulty level
`porciones`	`int \| null`	Number of servings
`imagen`	`str \| null`	Cover image URL
`calorias`	`int \| null`	Calories per serving
`porcentaje_match`	`float`	Percentage of recipe ingredients found in pantry
`usa_criticos`	`bool`	`true` if at least one matched ingredient is in `amarillo`/`rojo`

[
  {
    "id_receta": 14,
    "nombre": "Tortilla de papas",
    "descripcion": "Clásica tortilla española con papas y cebolla.",
    "tiempo_preparacion": 30,
    "dificultad": "media",
    "porciones": 4,
    "imagen": null,
    "calorias": 320,
    "porcentaje_match": 100.0,
    "usa_criticos": true
  }
]

A recipe only appears in Tengo Hambre results if at least 70 % of its ingredients are present in the pantry (under the active solo_criticos filter). Recipes with fewer matching ingredients are silently excluded to keep suggestions actionable.

Run Tengo Hambre with solo_criticos=false to see every recipe you could cook from your full pantry, not just ones that use items about to expire.

API Overview

Method	Path	Description
`POST`	`/api/v1/recetas/`	Create a recipe
`GET`	`/api/v1/recetas/`	List all public recipes
`GET`	`/api/v1/recetas/{id_receta}`	Get recipe details
`PATCH`	`/api/v1/recetas/{id_receta}`	Update a recipe
`DELETE`	`/api/v1/recetas/{id_receta}`	Delete a recipe
`POST`	`/api/v1/recetas/tags`	Create a tag
`GET`	`/api/v1/recetas/tags`	List all tags
`POST`	`/api/v1/recetas/{id_receta}/favorito`	Favourite a recipe
`DELETE`	`/api/v1/recetas/{id_receta}/favorito`	Unfavourite a recipe
`GET`	`/api/v1/recetas/favoritos/mios`	List your favourites
`GET`	`/api/v1/tengo-hambre/{id_hogar}`	Get personalised recipe suggestions

Getting Started

Core Concepts

Guides

Deployment

Tengo Hambre: Recipe Suggestions from Expiring Items

The Recipe Data Model

Core Fields (`RecetaCreate`)

Ingredient Entry (`RecetaIngredienteCreate`)

Creating a Recipe

Detail Response (`RecetaDetalleResponse`)

Recipe Tags

Recipe Favourites

The Tengo Hambre Engine

Query Parameters

Example Request

Suggestion Response (`SugerenciaResponse`)

API Overview

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Deployment

Documentation Index

​The Recipe Data Model

​Core Fields (RecetaCreate)

​Ingredient Entry (RecetaIngredienteCreate)

​Creating a Recipe

​Detail Response (RecetaDetalleResponse)

​Recipe Tags

​Recipe Favourites

​The Tengo Hambre Engine

​Query Parameters

​Example Request

​Suggestion Response (SugerenciaResponse)

​API Overview

Build docs developers (and LLMs) love

The Recipe Data Model

Core Fields (`RecetaCreate`)

Ingredient Entry (`RecetaIngredienteCreate`)

Creating a Recipe

Detail Response (`RecetaDetalleResponse`)

Recipe Tags

Recipe Favourites

The Tengo Hambre Engine

Query Parameters

Example Request

Suggestion Response (`SugerenciaResponse`)

API Overview