Ingredient Knowledge System

Resolves cosmetic ingredient identities and enriches them with regulatory and scientific data.

Setup

# 1. Install dependencies
pip install -r requirements.txt

# 2. Create .env file
cp .env.example .env
# Edit .env with your Azure OpenAI credentials

# 3. Run both services
python ingredient_knowledge_service.py  # Port 8000
python db_explorer_service.py          # Port 8001

See SERVICES.md for service details.

---

System I/O

IN (What you provide):

• Ingredient name (e.g., "Glycerin")
• Optional: CAS number, INCI name, EC number
• Request: resolve, ingest, refresh, or status check

OUT (What you get):

• Canonical INCI name
• CAS number
• Molecular properties (weight, HLB, etc.)
• Regulatory status (EU CosIng)
• Supplier pricing info
• Data completeness score

---

Architecture

┌─────────────────┐      A2A (port 8000)      ┌─────────────────────────┐
│  Other Agents   │ ────────────────────────▶ │ Ingredient Knowledge    │
│  (Python)       │    JSON-RPC resolve()     │ Service                 │
└─────────────────┘                           │ • Identity matching       │
                                              │ • Web enrichment        │
┌─────────────────┐      HTTP (port 8001)     │ • Unified response      │
│  Next.js        │ ────────────────────────▶ └─────────────────────────┘
│  Frontend       │    REST API + SSE         ┌─────────────────────────┐
│  (localhost:8080)│                           │ DB Explorer Service     │
└─────────────────┘                           │ • Search UI endpoints   │
                                              │ • Compare & Save        │
                                              │ • SSE progress streams  │
                                              └─────────────────────────┘

---

Quick Start

# Terminal 1 - A2A Service (agents use this)
python ingredient_knowledge_service.py

# Terminal 2 - DB Explorer (frontend uses this)
python db_explorer_service.py

Custom Ports

# Custom port for Ingredient Knowledge Service (default: 8000)

#env file
IKA_PORT=9000 
#in your terminal
python ingredient_knowledge_service.py

# Custom port for DB Explorer Service (default: 8001)

#env file
EXPLORER_PORT=9001
#in your terminal
 python db_explorer_service.py