Python - AdMesh Documentation

Overview

The admesh-weave-python SDK is a backend Python package that fetches personalized recommendations from AdMesh. Use it to retrieve recommendations that your LLM can naturally weave into responses. When to use this SDK:

You want to embed recommendations directly in LLM responses (Weave Ad Format)
You need backend control over recommendation fetching
You’re building a custom LLM integration with Python

When NOT to use this SDK:

You only need frontend recommendations (use admesh-ui-sdk instead)
You want a separate recommendations panel (use Tail/Product Format with admesh-ui-sdk)

Quick Start

Install the package:

pip install admesh-weave-python

Initialize the client:

from admesh_weave import AdMeshClient

client = AdMeshClient(api_key="your-api-key")

Fetch recommendations:

result = await client.get_recommendations_for_weave(
    session_id=session_id,
    message_id=message_id,
    query=user_query
)

if result["found"]:
    context = "\n".join([
        f"- {r['product_title']}: {r['click_url']}"
        for r in result["recommendations"]
    ])

Requirements

Python 3.8 or higher
API key from AdMesh dashboard
Full type hints included
Works with FastAPI, Flask, Django, etc.

Installation Methods

pip (recommended):

pip install admesh-weave-python

Poetry:

poetry add admesh-weave-python

pipenv:

pipenv install admesh-weave-python

Core Concepts

AdMeshClient

The main client for fetching recommendations. Initialize once and reuse across your application.

from admesh_weave import AdMeshClient

client = AdMeshClient(api_key="your-api-key")

Configuration options:

api_key (required): Your AdMesh API key from the dashboard
api_base_url (optional): Custom API endpoint (defaults to production)

Session and Message IDs

AdMesh uses IDs to track user interactions:

session_id: Unique identifier for a user’s conversation session
message_id: Unique identifier for each individual message/query

import uuid

# Your application generates these IDs
session_id = str(uuid.uuid4())  # Generate once per conversation
message_id = str(uuid.uuid4())  # Generate for each message

Your backend is responsible for generating and managing session and message IDs. The SDK accepts these IDs but does not generate them. These IDs must be provided by the frontend.

Basic Usage

Async Usage (Recommended)

from admesh_weave import AdMeshClient

client = AdMeshClient(api_key="your-api-key")

async def handle_user_query(user_query: str, session_id: str, message_id: str):
    # Fetch recommendations
    result = await client.get_recommendations_for_weave(
        session_id=session_id,  # Required: Must be provided by frontend
        message_id=message_id,  # Required: Must be provided by frontend
        query=user_query,       # Required
        latency_budget_ms=10000  # Optional: 10 second latency budget for auction processing
    )
    
    if result["found"]:
        recommendations = result["recommendations"]
        # Pass to your LLM
        return format_llm_response(user_query, recommendations)
    else:
        # No recommendations available
        return format_llm_response(user_query, [])

Synchronous Usage

from admesh_weave import AdMeshClient

client = AdMeshClient(api_key="your-api-key")

def handle_user_query(user_query: str, session_id: str, message_id: str):
    # Fetch recommendations (sync)
    result = client.get_recommendations_for_weave_sync(
        session_id=session_id,
        message_id=message_id,
        query=user_query
    )
    
    if result["found"]:
        recommendations = result["recommendations"]
        return format_llm_response(user_query, recommendations)

Integration Examples

FastAPI Example

from fastapi import FastAPI, HTTPException
from admesh_weave import AdMeshClient
from pydantic import BaseModel

app = FastAPI()
client = AdMeshClient(api_key="your-api-key")

class ChatRequest(BaseModel):
    session_id: str
    message_id: str
    query: str

@app.post("/api/chat")
async def chat(request: ChatRequest):
    try:
        result = await client.get_recommendations_for_weave(
            session_id=request.session_id,
            message_id=request.message_id,
            query=request.query
        )
        
        return {
            "found": result["found"],
            "recommendations": result.get("recommendations", [])
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Flask Example

from flask import Flask, request, jsonify
from admesh_weave import AdMeshClient

app = Flask(__name__)
client = AdMeshClient(api_key="your-api-key")

@app.route('/api/chat', methods=['POST'])
def chat():
    data = request.json
    
    result = client.get_recommendations_for_weave_sync(
        session_id=data['session_id'],
        message_id=data['message_id'],
        query=data['query']
    )
    
    return jsonify({
        "found": result["found"],
        "recommendations": result.get("recommendations", [])
    })

Environment Variables

Store your API key securely using environment variables:

# .env
ADMESH_API_KEY=your-api-key-here

import os
from admesh_weave import AdMeshClient

client = AdMeshClient(api_key=os.environ["ADMESH_API_KEY"])

API Methods

get_recommendations_for_weave()

Fetches recommendations for a given query that can be woven into LLM responses.

result = await client.get_recommendations_for_weave(
    session_id: str,           # Required: Must be provided by frontend
    message_id: str,           # Required: Must be provided by frontend
    query: str,                # Required: User query for contextual recommendations
    latency_budget_ms: int = None,  # Optional: Latency budget for auction processing (milliseconds)
    messages: List[dict] = None,   # Optional: Conversation history
    locale: str = None,            # Optional: User language in BCP 47 format (e.g., "en-US")
    geo: str = None,              # Optional: User country code in ISO 3166-1 alpha-2 format (e.g., "US")
    user_id: str = None,          # Optional: Anonymous hashed user ID
    model: str = None,            # Optional: AI model identifier (e.g., "gpt-4o")
    platform_id: str = None,      # Optional: Platform identifier
    platform_surface: str = None, # Optional: Platform surface (e.g., "web")
    timeout_ms: int = None        # Optional: Max wait time (default: calculated from latency_budget_ms or 30000ms)
)

Note: HTTP timeout is automatically calculated from latency_budget_ms when provided: max(latency_budget_ms * 3, 30000). This ensures the HTTP request doesn’t timeout before the auction completes. If latency_budget_ms is not provided, defaults to 30 seconds or timeout_ms if specified. Format Filtering: This method only returns recommendations with “weave” format. If the recommendation format is not “weave”, the method returns {"found": False, "error": "Preferred format is not weave"}. Example:

result = await client.get_recommendations_for_weave(
    session_id='session-abc123',  # Required: Must be provided by frontend
    message_id='msg-xyz789',      # Required: Must be provided by frontend
    query='best project management tools',  # Required
    latency_budget_ms=10000  # Optional: 10 second latency budget for auction processing
)

if result["found"]:
    print(f"Found {len(result['recommendations'])} recommendations")
    for rec in result["recommendations"]:
        print(f"- {rec['title']}: {rec['click_url']}")
        weave_summary = rec.get('weave_summary') or rec.get('creative_input', {}).get('short_description')
        print(f"  Summary: {weave_summary}")
else:
    print('No recommendations found:', result.get('error'))

Returns:

{
    "found": bool,                         # Whether recommendations were found
    "recommendations": List[dict],         # Array of recommendations (if found)
    "query": str,                          # Original query
    "request_id": str,                     # Request ID
    "error": str                           # Error message if not found
}

get_recommendations_for_weave_sync()

Synchronous version of get_recommendations_for_weave(). Same parameters and return type.

Troubleshooting

No recommendations returned

Possible causes:

Query is too generic (try more specific queries)
No active campaigns match the query
API key is invalid
Format is not “weave” (SDK only returns “weave” format recommendations)

Solution:

Use more specific queries (e.g., “best CRM for startups” instead of “software”)
Check that your AdMesh account has active campaigns
Verify API key in environment variables
Note: If format is not “weave”, the SDK returns {"found": False, "error": "Preferred format is not weave"}

API key errors

Check:

ADMESH_API_KEY is set in environment variables
API key is valid (check dashboard)
No extra whitespace in the key value

Example:

import os
print(f"API Key: {os.environ.get('ADMESH_API_KEY', 'NOT SET')}")

Type errors

Solution:

Ensure Python 3.8 or higher
Install type stubs if using mypy: pip install types-httpx
Check that all required parameters are provided

Network/timeout errors

Check:

Server has internet access
No firewall blocking outbound requests
Network is stable

Solution:

Increase timeout: timeout_ms=60000
Implement retry logic with exponential backoff
Check server network configuration

Next Steps

Weave Ad Format Guide: Complete integration guide for embedding recommendations in LLM responses - /platforms/weave-ad-format Frontend SDK: Install admesh-ui-sdk to detect and track embedded links on the frontend - /ui-sdk/installation

You’re ready to start integrating.
Install admesh-weave-python, fetch recommendations, and pass them to your LLM for natural weaving into responses.

Documentation Index

​Overview

​Quick Start

​Requirements

​Installation Methods

​Core Concepts

​AdMeshClient

​Session and Message IDs

​Basic Usage

​Async Usage (Recommended)

​Synchronous Usage

​Integration Examples

​FastAPI Example

​Flask Example

​Environment Variables

​API Methods

​get_recommendations_for_weave()

​get_recommendations_for_weave_sync()

​Troubleshooting

​No recommendations returned

​API key errors

​Type errors

​Network/timeout errors

​Next Steps

Overview

Quick Start

Requirements

Installation Methods

Core Concepts

AdMeshClient

Session and Message IDs

Basic Usage

Async Usage (Recommended)

Synchronous Usage

Integration Examples

FastAPI Example

Flask Example

Environment Variables

API Methods

get_recommendations_for_weave()

get_recommendations_for_weave_sync()

Troubleshooting

No recommendations returned

API key errors

Type errors

Network/timeout errors

Next Steps