Hairpin SDK

A Python SDK for embedding contextual ads in AI agents. The Hairpin SDK allows developers to easily integrate relevant, contextual advertisements into their AI applications.

Features

• Simple, one-line integration with get_ad(context)
• Contextual ad matching based on agent conversation
• Automatic impression tracking
• Support for multiple platforms (CLI, web, etc.)
• Token-based authentication
• Rate limiting and security best practices

Installation

pip install hairpin-sdk

Quick Start

1. Get your API key from the Hairpin dashboard
2. Set your API key as an environment variable:

   export HAIRPIN_API_KEY=your_api_key_here

3. Use the SDK in your code:

   from hairpin import get_ad
   
   # Get a contextual ad
   ad = get_ad(context="explaining AI concepts", platform="cli")
   
   # Display the ad
   print(f"{ad['title']} – {ad['cta_url']}")

Environment Variables

• HAIRPIN_API_KEY (required): Your API key for authentication
• HAIRPIN_API_URL (optional): API endpoint URL (defaults to http://localhost:5000)
• HAIRPIN_AGENT_ID (optional): Unique identifier for your agent (for tracking)

API Reference

get_ad(context: str, platform: str = "cli") -> dict

Request a contextual ad based on the provided context.

Parameters:

• context (str): The context in which the ad will be displayed
• platform (str): The platform where the ad will be shown (default: "cli")

Returns:

{
    "title": str,        # Ad title
    "description": str,  # Ad description
    "cta_url": str,      # Call-to-action URL
    "sponsor_name": str  # Sponsor's name
}

HairpinClient

For more advanced usage, you can use the HairpinClient class directly:

from hairpin import HairpinClient

client = HairpinClient(api_key="your_key_here")  # Or use HAIRPIN_API_KEY env var
ad = client.get_ad(context="your context")

Examples

Check out the examples/ directory for complete usage examples:

• basic_usage.py: Simple script demonstrating SDK usage
• agent_integration.py: Example integration with an AI agent

Development

1. Clone the repository:

   git clone https://github.com/hairpin/hairpin-sdk.git
   cd hairpin-sdk

2. Install development dependencies:

   pip install -e ".[dev]"

3. Run tests:

   pytest

Security

• All requests are authenticated using API keys
• Rate limiting is applied to prevent abuse
• Only agent-level tracking is used (no cookies or user IDs)
• All requests are made over HTTPS

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details