URPIC — Universal Recommendation Platform for Industry & Commerce

URPIC is a cross-industry, fairness-aware, temporally-adaptive recommendation platform built on the Multi-FIT Temporal Encoder architecture. It provides a single, unified recommendation infrastructure that adapts to the data schemas, optimization objectives, and regulatory constraints of multiple industries through a pluggable adapter system.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         INPUT SOURCES                               │
│  User Interaction History │ Item Catalog │ Exogenous Event Stream   │
└────────────────┬──────────────────────────────────────┬────────────┘
                 │                                      │
                 ▼                                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│              MULTI-FIT TEMPORAL ENCODER (Novel)                     │
│                                                                     │
│  Block A: High-Frequency Transformer (recent 50 interactions)       │
│  Block B: Low-Frequency TCN (full history, dilated convolutions)    │
│  Block C: Cross-Signal Attention (exogenous event fusion)           │
│  Block D: Irregular Time-Gap Encoder (Time2Vec)                     │
│  Regime-Shift Detector (CUSUM change-point detection)               │
└────────────────────────────┬────────────────────────────────────────┘
                             │  User Preference Vector
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    ANN RETRIEVAL LAYER                              │
│  FAISS-backed approximate nearest-neighbor search + graph expansion │
└────────────────────────────┬────────────────────────────────────────┘
                             │  Candidate Set (100-150 items)
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│              MULTI-OBJECTIVE RANKER                                 │
│  Shared MLP + per-objective heads + BPR training loss               │
│  Objectives configured per industry adapter                         │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│           POLICY & GOVERNANCE ENGINE (Unique)                       │
│  Constraint Solver │ Audit Logger │ Fairness Monitor                │
│  HIPAA · ECOA · EEOC · FINRA · COPPA · NIST AI RMF                 │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    OUTPUT TARGETS                                   │
│  REST API │ LLM/Agent API │ Audit Log │ Fairness Dashboard          │
└─────────────────────────────────────────────────────────────────────┘

---

Key Technical Innovations

1. Multi-FIT Temporal Encoder

Unlike standard sequential recommendation models (SASRec, BERT4Rec) that treat all time steps as equally spaced, Multi-FIT explicitly models:

• Irregular time gaps between events using Time2Vec sinusoidal embeddings
• Multi-resolution temporal patterns via parallel Transformer (short-term) and TCN (long-term) branches
• Exogenous event conditioning via cross-attention between user behavior and external signals
• Preference regime shifts via CUSUM change-point detection with soft re-weighting

2. Architecturally Integrated Governance

Regulatory compliance is not a post-hoc filter — it is embedded as a first-class component of the inference pipeline. Every recommendation decision is:

• Checked against hard regulatory constraints before being returned
• Logged with full decision context in an immutable audit trail
• Monitored for fairness metric drift in real time

3. Native LLM/Agent API

A dedicated /recommend/agent endpoint accepts OpenAI-style message arrays, enabling URPIC to serve as a tool in LLM agent pipelines for conversational recommendation.

---

Industry Adapters

Industry	Objectives	Key Constraints	Regulatory Basis
Retail	Relevance, Diversity, Novelty, Popularity	COPPA age gate, brand safety, stock	COPPA, CCPA
Healthcare	Clinical Relevance, Safety, Diversity	HIPAA PHI exclusion, safety minimum, contraindication	HIPAA, FDA, CMS
Finance	Suitability, Risk Fit, Diversity	ECOA protected attribute exclusion, suitability minimum	ECOA, FINRA, CFPB
Workforce	Skill Match, Career Fit, Diversity	EEOC exclusion, ADA accessibility, ADEA age neutrality	EEOC, Title VII, ADA, ADEA

---

Quickstart

1. Install

git clone https://github.com/YOUR_USERNAME/urpic-core.git
cd urpic-core
pip install -e ".[dev]"

2. Run the API server

python serve.py
# API available at http://localhost:8000
# Interactive docs at http://localhost:8000/docs

3. Make a recommendation request

curl -X POST http://localhost:8000/recommend \
  -H "X-URPIC-API-Key: dev-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001",
    "industry": "retail",
    "interaction_history": [
      {"item_id": 42, "timestamp": 1700000000.0, "event_type": "click"},
      {"item_id": 87, "timestamp": 1700003600.0, "event_type": "purchase"},
      {"item_id": 15, "timestamp": 1700007200.0, "event_type": "view"}
    ],
    "top_k": 10
  }'

4. Run tests

pytest tests/ -v

5. Docker deployment

docker-compose up --build

---

Project Structure

urpic-core/
├── urpic/
│   ├── encoder/
│   │   ├── multifit.py          # Multi-FIT Temporal Encoder (core)
│   │   ├── time_embedding.py    # Time2Vec irregular time-gap embedding
│   │   └── regime_detector.py   # CUSUM regime-shift detector
│   ├── retrieval/
│   │   ├── ann_index.py         # FAISS ANN index
│   │   └── candidate_retriever.py # Two-stage retrieval with graph expansion
│   ├── ranking/
│   │   ├── ranker.py            # Multi-objective neural ranker
│   │   ├── objectives.py        # Objective configs per industry
│   │   └── loss.py              # BPR pairwise ranking loss
│   ├── governance/
│   │   ├── audit_log.py         # SQLite-backed immutable audit logger
│   │   ├── constraint_solver.py # Hard regulatory constraint enforcement
│   │   ├── fairness_monitor.py  # Real-time fairness metric tracking
│   │   └── policy_engine.py     # Unified governance orchestrator
│   ├── adapters/
│   │   ├── base.py              # Abstract adapter base class
│   │   ├── retail.py            # Retail & Media adapter
│   │   ├── healthcare.py        # Healthcare & Clinical adapter
│   │   ├── finance.py           # Financial Services adapter
│   │   ├── workforce.py         # Workforce & Talent adapter
│   │   └── registry.py          # Dynamic adapter registry
│   └── api/
│       └── app.py               # FastAPI REST + Agent API
├── tests/
│   ├── test_encoder.py
│   └── test_governance.py
├── serve.py                     # API server entry point
├── requirements.txt
├── setup.py
├── Dockerfile
└── docker-compose.yml

---

API Reference

Endpoint	Method	Description
/health	GET	Health check
/industries	GET	List available adapters
/recommend	POST	Standard recommendation
/recommend/agent	POST	LLM/Agent-style recommendation
/audit/{user_id}	GET	User audit log
/fairness/metrics	GET	Fairness dashboard

All endpoints require the X-URPIC-API-Key header.

---

License

Apache License 2.0. See LICENSE for details.