Skip to content

SERVICES.md

Latest commit

 

History

History
103 lines (78 loc) · 3.49 KB

SERVICES.md

File metadata and controls

103 lines (78 loc) · 3.49 KB
Raw

Backend Services

Two services run side-by-side. Know which one to use.

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

Service Overview

Service Port Purpose Called By
Ingredient Knowledge 8000 Ingredient resolution & enrichment Other agents (A2A)
DB Explorer 8001 Human-friendly DB exploration Next.js frontend

Ingredient Knowledge Service (Port 8000)

What it does:

  • Resolves ingredient identities from names/CAS/INCI
  • Enriches ingredient data from web sources (CosIng, PubChem, suppliers)
  • Returns unified data structure via A2A protocol

Who calls it:

  • Other agents via A2A JSON-RPC protocol
  • Not called by frontend directly

Run it:

python ingredient_knowledge_service.py

Key endpoint:

  • POST / - A2A JSON-RPC endpoint (resolve, ingest, refresh, status)

DB Explorer Service (Port 8001)

What it does:

  • Provides search UI endpoints (DB, Web, Deep search modes)
  • Streams progress via Server-Sent Events (SSE)
  • Compares DB vs Web data with side-by-side view
  • Saves selected web fields to database

Who calls it:

  • Next.js frontend at http://localhost:8080

Run it:

python db_explorer_service.py

Key endpoints:

Method Endpoint Description
GET /stream/search?mode=deep&query=Glycerin SSE streaming search
POST /compare Compare DB vs Web data
POST /save-selected Save web fields to DB
GET /ingredients List all ingredients
GET /enrichment-status Data completeness stats

Requirements

pip install -r requirements.txt

Create .env file with Azure OpenAI credentials:

AZURE_OPENAI_KEY_0=your_key_here
AZURE_OPENAI_ENDPOINT_0=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_0=gpt-4o-mini

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  │
                                              └─────────────────────────┘