Polar Llama Documentation

Version 0.2.2 introduces powerful embedding and vector operations that enable semantic search, document similarity, and clustering capabilities. Generate embeddings from your text data and perform efficient similarity searches using industry-standard algorithms.

import polars as pl
from polar_llama import embed_async, Provider

# Create a DataFrame with text to embed
df = pl.DataFrame({
    "id": [1, 2, 3],
    "text": [
        "Machine learning is a subset of artificial intelligence",
        "Deep learning uses neural networks with many layers",
        "Natural language processing analyzes human language"
    ]
})

# Generate embeddings
df = df.with_columns(
    embedding=embed_async(
        "text",
        provider=Provider.OPENAI,
        model="text-embedding-3-small"
    )
)

print(df.select(["id", "text", "embedding"]))

The new cost analytics feature helps you monitor and manage your AI spending by calculating the cost of each inference call. Track costs per request, aggregate spending over time, and identify opportunities to optimize your LLM usage.

import polars as pl
from polar_llama import inference_async, calculate_cost, Provider

# Run inference and track costs
df = df.with_columns(
    answer=inference_async(
        'prompt',
        provider=Provider.OPENAI,
        model='gpt-4o-mini',
        return_usage=True  # Enable usage tracking
    )
)

# Calculate cost for each request
df = df.with_columns(
    cost=calculate_cost(
        "answer",
        provider=Provider.OPENAI,
        model='gpt-4o-mini'
    )
)

# Get total cost
total_cost = df.select(pl.col("cost").sum()).item()
print(f"Total inference cost: ${total_cost:.4f}")

# Cost breakdown by category
cost_by_category = df.group_by("category").agg(
    pl.col("cost").sum().alias("total_cost"),
    pl.col("cost").mean().alias("avg_cost"),
    pl.col("cost").count().alias("request_count")
)
print(cost_by_category)

Taxonomy-based tagging is a powerful feature that allows you to classify documents according to a custom taxonomy with detailed reasoning, reflection, and confidence scores. This feature is particularly useful for content classification, customer support routing, email triage, sentiment analysis, and multi-label classification.

import polars as pl
from polar_llama import tag_taxonomy, Provider

# Define your taxonomy
taxonomy = {
    "sentiment": {
        "description": "The emotional tone of the text",
        "values": {
            "positive": "Text expresses positive emotions or favorable opinions",
            "negative": "Text expresses negative emotions or unfavorable opinions",
            "neutral": "Text is factual and objective without clear emotional content"
        }
    },
    "urgency": {
        "description": "How urgent the content is",
        "values": {
            "high": "Requires immediate attention",
            "medium": "Should be addressed soon",
            "low": "Can be addressed at any time"
        }
    }
}

# Create a dataframe
df = pl.DataFrame({
    "id": [1, 2],
    "message": [
        "URGENT: Server is down!",
        "Thanks for your help yesterday."
    ]
})

# Apply taxonomy tagging
result = df.with_columns(
    tags=tag_taxonomy(
        pl.col("message"),
        taxonomy,
        provider=Provider.GROQ,
        model="openai/gpt-oss-120b"
    )
)

# Extract specific values
result.select([
    "message",
    pl.col("tags").struct.field("sentiment").struct.field("value").alias("sentiment"),
    pl.col("tags").struct.field("sentiment").struct.field("confidence").alias("confidence"),
    pl.col("tags").struct.field("urgency").struct.field("value").alias("urgency")
])

A taxonomy is defined as a dictionary with the following structure:

taxonomy = {
    "field_name": {
        "description": "What this field represents",
        "values": {
            "value1": "Definition of value1",
            "value2": "Definition of value2",
            # ... more values
        }
    },
    # ... more fields
}

Each tagged document returns a Struct with the following nested structure:

{
    "field_name": {
        "thinking": {
            "value1": "Reasoning about why value1 might apply...",
            "value2": "Reasoning about why value2 might apply...",
            # ... reasoning for each possible value
        },
        "reflection": "Overall reflection on the analysis of this field...",
        "value": "selected_value",  # The chosen value
        "confidence": 0.87  # Confidence score (0.0 to 1.0)
    },
    # ... more fields
}

def tag_taxonomy(
    expr: IntoExpr,
    taxonomy: Dict[str, Dict[str, Any]],
    *,
    provider: Optional[Union[str, Provider]] = None,
    model: Optional[str] = None,
) -> pl.Expr

• 1
  Start Simple:

  Begin with 2-3 fields and expand as needed

• 2
  Test Definitions:

  Verify that your value definitions are clear and distinguishable

• 3
  Use Confidence Scores:

  Filter or flag low-confidence results for review

• 4
  Validate Results:

  Spot-check classifications to ensure quality

• 5
  Iterate:

  Refine your taxonomy based on results

• 6
  Handle Errors:

  Always check for and handle error cases

Structured outputs allow you to define the exact schema you want the LLM to follow, ensuring responses are properly formatted and can be directly used in your data pipelines. This is perfect for extracting specific information, generating consistent data, or integrating LLM outputs with databases and APIs.

import polars as pl
from polar_llama import string_to_message, inference_async, Provider
from pydantic import BaseModel

# Define your output schema
class ProductInfo(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

# Create prompts
prompts = [
    "Extract product info: iPhone 15 Pro for $999 in Electronics, available",
    "Extract product info: Nike Air Max shoes for $129.99 in Footwear, sold out",
    "Extract product info: Laptop Stand for $49.99 in Accessories, in stock"
]

df = pl.DataFrame({'prompt': prompts})

# Convert to messages
df = df.with_columns(
    message=string_to_message("prompt", message_type='user')
)

# Run inference with structured output
df = df.with_columns(
    product=inference_async(
        'message',
        provider=Provider.OPENAI,
        model='gpt-4o-2024-08-06',
        response_model=ProductInfo  # Specify your Pydantic model
    )
)

# Access structured fields directly
print(df.select(['product']))

import polars as pl
from polar_llama import string_to_message, inference_async

# Create a DataFrame with system prompts and user questions
df = pl.DataFrame({
    "system_prompt": [
        "You are a helpful assistant.",
        "You are a math expert.",
        "You are a creative writer."
    ],
    "user_question": [
        "What's the weather like today?",
        "Solve x^2 + 5x + 6 = 0",
        "Write a haiku about coding"
    ]
})

# Convert both columns to messages
df = df.with_columns([
    string_to_message("system_prompt", message_type="system").alias("system_message"),
    string_to_message("user_question", message_type="user").alias("user_message")
])

# Combine messages into conversations
from polar_llama import combine_messages, inference_messages
df = df.with_columns(
    combine_messages("system_message", "user_message").alias("conversation")
)

# Run inference with combined messages
df = df.with_columns(
    inference_messages("conversation",
           provider="openai",
           model="gpt-4").alias("response")
)

print(df.select(["user_question", "response"]))

import polars as pl
from polar_llama import string_to_message, inference_async, Provider

# Load customer feedback data
feedback_df = pl.DataFrame({
    'customer_id': [101, 102, 103, 104, 105],
    'feedback': [
        'The product is amazing but shipping was slow',
        'Great quality, highly recommend!',
        'Disappointed with customer service',
        'Perfect for my needs, will buy again',
        'Product arrived damaged, requesting refund'
    ]
})

# Create sentiment analysis prompts
sentiment_prompt = """Analyze the sentiment of this customer feedback
and classify it as Positive, Negative, or Neutral.
Also provide a brief reason.

Feedback: {feedback}"""

df = feedback_df.with_columns(
    prompt=pl.format(sentiment_prompt, pl.col('feedback'))
)

# Convert to messages and run inference
df = df.with_columns(
    message=string_to_message("prompt", message_type='user')
)

df = df.with_columns(
    sentiment_analysis=inference_async('message',
                                      provider=Provider.OPENAI,
                                      model='gpt-4o-mini')
)

# Extract key insights
print(df.select(['customer_id', 'feedback', 'sentiment_analysis']))