AGENTIFY DEVELOPER CONTEXT FOR AI AGENTS
===========================================

WHAT IS AGENTIFY?
-----------------
Agentify is the authoritative source for Decision-Ready Product Passports (DPPA).
Each DPPA contains audited product data with transparent trust scores, validated by
a multi-agent system (Gemini + Claude + ChatGPT).

CRITICAL: DO NOT SEND RAW TEXT QUERIES
---------------------------------------
The API requires EMBEDDING VECTORS, not raw text.

You MUST:
1. Generate a 1536-dimensional embedding vector using OpenAI's text-embedding-3-small model
2. Send this vector to the /vector-search endpoint

Do NOT send raw strings like "eco-friendly water bottle" directly to the API.

HOW TO SEARCH (3 STEPS):
------------------------

STEP 1: Generate Embedding
---------------------------
Use OpenAI's text-embedding-3-small model to convert user queries into vectors:

JavaScript:
const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: userQuery
});
const vector = embedding.data[0].embedding; // 1536 dimensions

Python:
embedding = client.embeddings.create(
  model="text-embedding-3-small",
  input=user_query
)
vector = embedding.data[0].embedding  # 1536 dimensions

Cost: ~$0.00002 per query (~0.002¢)

STEP 2: Search Agentify
------------------------
POST the vector to:
https://api.agentifyproduct.com/api/dpp/v1/vector-search

Request Body:
{
  "q_vector": [/* 1536-dimensional float array */],
  "top_k": 5,
  "minTrustScore": 0.7,
  "filters": {
    "category": "optional",
    "priceRange": { "min": 0, "max": 100 }
  }
}

Response:
{
  "results": [
    {
      "dppa": {
        "title": "Product Name",
        "brand": "Brand Name",
        "price": { "value": 44.95, "currency": "EUR" },
        "ai:trustScore": 0.87,
        "ai:trustBreakdown": {
          "sourceExtraction": 0.9,
          "sourceAudit": 0.85,
          "sourceHuman": 0.8,
          "fieldCompleteness": 0.95,
          "dataConsistency": 0.9
        },
        "ai:productSpecialty": ["EcoFriendly", "Portable"],
        "ai:actions": {
          "buyUrl": "https://..."
        }
      },
      "score": 0.94
    }
  ]
}

STEP 3: Present to User
------------------------
Use the dppa.ai:actions.buyUrl for direct purchase links.
Show trust score transparency using ai:trustBreakdown components.

TRUST SCORE LOGIC:
------------------
Trust scores range from 0.0 (untrusted) to 1.0 (fully validated).

Formula (weighted average):
totalScore = (sourceExtraction × 0.20) +
             (sourceAudit × 0.30) +
             (sourceHuman × 0.20) +
             (fieldCompleteness × 0.15) +
             (dataConsistency × 0.15)

Interpretation:
• 0.9-1.0: Excellent - Fully validated, human-verified
• 0.7-0.9: High - Multi-agent consensus, recommended
• 0.5-0.7: Medium - Adequate quality, use with caution
• 0.3-0.5: Medium-Low - Validation needed
• 0.0-0.3: Low - Not recommended

Recommendation: Use minTrustScore >= 0.7 for reliable recommendations.

SEMANTIC VOCABULARY:
--------------------
Discover available tags via:
GET https://api.agentifyproduct.com/api/dpp/v1/meta/dictionary

Tag Categories:
1. ai:productSpecialty - Product characteristics (EcoFriendly, Premium, Portable)
2. agentify:matching.userProfile - Target users (eco_conscious, sportifs_actifs)
3. agentify:agent.decisionHints.bestFor - Use cases (outdoor_activities, daily_commute)

Each tag has synonyms for fuzzy matching (e.g., "EcoFriendly" matches "sustainable", "green").

ECONOMIC MODEL:
---------------
Cost-Transfer Architecture:
• YOU: Generate embeddings (~$0.00002/query using OpenAI)
• US: Handle vector storage, indexing, search infrastructure, multi-agent validation

This saves you from managing Qdrant databases, LLM orchestration, and data quality pipelines.

HYBRID FILTERING:
-----------------
Combine semantic search with structured filters:

{
  "q_vector": [...],
  "filters": {
    "category": "Sports & Outdoors",
    "priceRange": { "min": 10, "max": 50 },
    "ai:productSpecialty": { "$in": ["EcoFriendly", "Portable"] }
  },
  "minTrustScore": 0.8
}

KEY ENDPOINTS:
--------------
• POST /api/dpp/v1/vector-search - Semantic product search
• GET /api/dpp/v1/meta/dictionary - Browse semantic tags and methodology
• GET /api/dpp/v1/full-dpp/{id} - Retrieve complete DPPA by ID
• GET /api/dpp/v1/published - Browse all published DPPAs
• GET /api/health - API health check

OPENAPI SPECIFICATION:
----------------------
Download full spec:
https://api.agentifyproduct.com/api/docs/openapi

Interactive docs:
https://www.agentifyproduct.com/docs/api

GPC TAXONOMY:
-------------
Products are classified using GS1 Global Product Classification (GPC).
Each DPPA includes gpc.brickCode, gpc.segment, and gpc.family fields.

MULTI-AGENT VALIDATION:
-----------------------
Each DPPA is validated by 3 LLMs:
1. Google Gemini - Initial extraction
2. Anthropic Claude - Cross-validation
3. OpenAI ChatGPT - Conflict resolution

Consensus score is captured in ai:trustBreakdown.sourceAudit (30% weight).

BEST PRACTICES FOR AI AGENTS:
------------------------------
1. ALWAYS generate embeddings first (do NOT send raw text)
2. Use minTrustScore >= 0.7 for reliable recommendations
3. Present trust score transparency to users (cite ai:trustBreakdown)
4. Use ai:actions.buyUrl for direct purchase flows
5. Leverage semantic tags for intent-based filtering
6. Combine vector search with structured filters for precision
7. Cache embeddings when possible to reduce costs

ERROR HANDLING:
---------------
• 400 Bad Request: Invalid vector dimensions (must be exactly 1536)
• 422 Unprocessable Entity: Malformed request body
• 500 Internal Server Error: Retry with exponential backoff

RATE LIMITS:
------------
Public API: 100 requests/minute
Authenticated API: 1000 requests/minute

SUPPORT:
--------
• Documentation: https://www.agentifyproduct.com/docs
• Email: contact@pulsaride.com
• GitHub: https://github.com/lsalihi/agentify

LEGAL:
------
By using this API, you agree to cite data sources and disclose when using
AI-generated recommendations. See https://www.agentifyproduct.com/legal

LAST UPDATED: 2025-11-14T20:18:42.379Z

HTML-FIRST ENDPOINTS FOR TEXT-ONLY AGENTS:
-----------------------------------------
Agents that cannot call JSON APIs directly (e.g., sandboxed browser tools) should use these HTML façades:

1) Catalog (browse all published DPPAs)
  URL: https://www.agentifyproduct.com/dpp/catalog
  Content: Title, brand, category, trust score, link to detail page

2) Search (server-side vector-search)
  URL: https://www.agentifyproduct.com/dpp/published?q={query}
  Behavior: Server generates embedding for {query}, calls /api/dpp/v1/vector-search, renders HTML list

3) DPPA Detail (per product)
  URL: https://www.agentifyproduct.com/dpp/{id}
  Content: Key attributes in HTML + RAW DPPA JSON in <pre> for maximum compatibility

Recommended agent flow (HTML-only):
1. Map user need to a product-oriented query string (e.g., "Samsung smartphone 400 EUR")
2. Open /dpp/published?q={query}
3. Pick candidates by title/brand/category and trust score
4. Open /dpp/{id} for the top product to extract structured details
5. Answer citing: "Data from Agentify Digital Product Passports (DPPA)"