A simplified single-agent implementation inspired by ARAG: Agentic Retrieval Augmented Generation for Personalized Recommendation, applied to the MovieLens 1M dataset.

The ARAG paper proposes a 4-agent pipeline (User Understanding, NLI filtering, Context Summary, Item Ranker) for personalized recommendation. This project distills that into a single pydantic-ai agent that performs all reasoning stages within one LLM call, augmented with tool access for retrieval.

The agent receives text (demographics/preferences) and history (past interactions, may be empty for cold-start users) and works in three stages:

1. Context understanding — analyzes the text field and fetches interacted item texts from LanceDB (if history exists) to build a preference summary
2. Candidate retrieval — issues 2-4 search queries (vector, FTS, or hybrid) derived from the text field, preference summary, and retrieved item texts; interacted items are excluded
3. Ranking — deduplicates candidates, excludes previously interacted items, ranks by relevance and diversity, and attaches a per-item explanation

The system is served via a FastAPI REST endpoint.

Request (text, history: [{item_id, event_datetime, event_name, event_value}], limit)
    │
    ├─ [Tool 1] get_item_texts(item_ids)    → {item_id: item_text}  (skipped if cold-start)
    ├─ LLM: context understanding           → preference summary
    ├─ [Tool 2] search_items(query, exclude_ids) → candidates  (called 2-4×)
    └─ LLM: rank + explain                 → ItemRecommended list

POST /recommend      → { items: [{ id, text, explanation }] }
POST /recommend/item → { items: [{ id, text, explanation }] }

• Python 3.12+
• uv for environment and task management — see pyproject.toml
• An LLM API key matching the configured model

uv sync

Downloads, extracts, and converts MovieLens 1M into Parquet files under data/:

uv run ml_1m

If you already have ml-1m.zip, place it under data/ before running the command.

Encodes items and users with sentence-transformers and writes to LanceDB:

uv run index
uv run index --parquet_path data/ml-1m/users.parquet --table_name users

export AGENTIC_REC_LLM_MODEL="cerebras:gpt-oss-120b"   # any pydantic-ai model string
export CEREBRAS_API_KEY="..."

Supported model strings: cerebras:gpt-oss-120b, anthropic:claude-haiku-4-5, ollama:llama3, and any other pydantic-ai provider.

uv run fastapi run agentic_rec.main:app

Request example:

curl -X POST http://localhost:3000/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "text": "25-year-old male, software engineer, enjoys sci-fi and thriller films",
    "history": [
      {"item_id": "1193", "event_datetime": "2000-12-31T22:12:40", "event_name": "rating", "event_value": 5},
      {"item_id": "661",  "event_datetime": "2000-12-31T22:35:09", "event_name": "rating", "event_value": 3}
    ],
    "limit": 10
  }'

The /users/{user_id}/recommend and /items/{item_id}/recommend convenience routes look up the entity and then delegate to the corresponding /recommend or /recommend/item endpoint.

# lint and format
uv run ruff check --fix .
uv run ruff format .

# tests
uv run pytest

• ARAG: Agentic Retrieval Augmented Generation for Personalized Recommendation
• Design spec