Metadata-Version: 2.4
Name: aice-reco-sdk
Version: 0.1.0
Summary: Python SDK for the Reco recommendation engine
Author-email: Arnold Opiyo <arnoldopiyo@adanianlabs.io>
Keywords: recommendation,recommendation-engine,recommender,machine-learning,api
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27

# AICE Reco SDK

Official Python SDK for the AICE Reco Recommendation Engine.

AICE Reco is a high-performance recommendation platform that learns from user behavior and serves personalized recommendations through a simple REST API.

This package is the official Python client for interacting with a running Reco server.

---

## Architecture

The system consists of two independent components.

```
               User Application
                      │
                      │
          ┌───────────▼───────────┐
          │   Python SDK (this)   │
          │     httpx client      │
          └───────────┬───────────┘
                      │ REST API
                      │
          ┌───────────▼───────────┐
          │     Reco Server       │
          │                       │
          │ Recommendation Engine │
          │ Training Pipeline     │
          │ Event Store           │
          │ Configuration Engine  │
          └───────────┬───────────┘
                      │
              PostgreSQL + pgvector
```

The SDK contains **no machine learning logic**.

All recommendation algorithms, model training, configuration management, and scoring run inside the Reco server. The SDK simply provides a clean Python interface to the REST API.

---

# Features

* User management
* Item catalog management
* Interaction tracking
* Personalized recommendations
* Asynchronous model training
* Job monitoring
* Recommendation explanations
* Vertical discovery
* Runtime configuration management
* Fully typed Python interface

---

# Requirements

* Python 3.11+
* Running Reco Server

---

# Installation

```bash
pip install aice-reco-sdk
```

---

# Quick Start

```python
from reco import RecoClient

client = RecoClient(
    base_url="http://localhost:8000",
    api_key="your-api-key",
)

client.create_user(
    "user-1",
    metadata={
        "country": "KE",
        "age": 29,
    },
)

client.create_item(
    "item-42",
    metadata={
        "category": "Electronics",
    },
)

client.track(
    user_id="user-1",
    item_id="item-42",
    event_type="purchase",
)

job = client.train()

recommendations = client.recommend(
    user_id="user-1",
    n=10,
)

for recommendation in recommendations.recommendations:
    print(
        recommendation.rank,
        recommendation.item_id,
        recommendation.score,
    )

client.close()
```

---

# Recommendation Lifecycle

A typical workflow looks like this.

```
Create Users
      │
      ▼
Create Items
      │
      ▼
Track User Events
      │
      ▼
Train Model
      │
      ▼
Generate Recommendations
```

Recommendations improve automatically as additional interaction events are collected and the model is retrained.

---

# User and Item Metadata

Reco stores arbitrary metadata alongside users and catalog items.

Example:

```python
client.create_user(
    "user-1",
    metadata={
        "country": "Kenya",
        "subscription": "Premium",
        "age": 31,
    },
)

client.create_item(
    "movie-12",
    metadata={
        "genre": "Action",
        "language": "English",
        "year": 2025,
    },
)
```

Metadata can later be used by recommendation models and future ranking strategies.

---

# Tracking Events

Interactions represent user behaviour.

```python
client.track(
    user_id="user-1",
    item_id="item-42",
    event_type="view",
)

client.track(
    user_id="user-1",
    item_id="item-42",
    event_type="purchase",
)
```

Common event types include:

* view
* click
* like
* add_to_cart
* purchase
* rating

Custom event types are also supported.

---

# Training

Training runs asynchronously.

```python
job = client.train()
```

Retrieve progress:

```python
status = client.job_status(job.job_id)

print(status.status)
print(status.progress)
```

---

# Getting Recommendations

```python
response = client.recommend(
    user_id="user-1",
    n=20,
)

for recommendation in response.recommendations:
    print(
        recommendation.item_id,
        recommendation.score,
        recommendation.explanation,
    )
```

Each recommendation contains

* Item ID
* Score
* Rank
* Explanation

---

# API Overview

| Method | Purpose |
|---------|---------|
| create_user | Create user |
| get_user | Retrieve user |
| update_user | Update user |
| create_item | Create catalog item |
| get_item | Retrieve item |
| update_item | Update item |
| track | Record interaction |
| recommend | Generate recommendations |
| train | Start model training |
| job_status | Monitor training progress |
| get_config | Retrieve project configuration |
| update_config | Update configuration |
| list_verticals | List available recommendation verticals |
| get_vertical | Retrieve a vertical definition |

---

# Error Handling

The SDK raises typed exceptions.

```python
from reco.exceptions import (
    AuthError,
    NotFoundError,
    ServerError,
)

try:
    client.recommend("user-1")
except NotFoundError:
    print("User not found.")
```

Exception hierarchy

```
RecoError
├── AuthError
├── ValidationError
├── NotFoundError
├── ConflictError
└── ServerError
```

---

# Running Your Own Server

The SDK communicates with a running Reco server.

A production deployment consists of:

* Reco API
* Worker process
* PostgreSQL
* pgvector
* pgmq

The official Docker deployment includes all required services and can be started using Docker Compose.

---

# Supported Recommendation Domains

Reco is designed around configurable verticals, allowing the same engine to power different recommendation scenarios.

Examples include:

* E-commerce
* Movies
* Music
* News
* Articles
* Retail
* Digital content
* Education
* Job matching

Each vertical defines its own default configuration while exposing runtime overrides through the API.

---

# Documentation

Project repository

https://github.com/Adalabsafricaltd/aice-packages/tree/staging/recommendation_engine

---