Opper

https://docs.opper.ai
Admin
Opper is a task completion platform for building reliable AI integrations, offering declarative...
Tokens:90,304
Snippets:309
Trust Score:6.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Opper Python SDK

Source: https://docs.opper.ai/overview/getting-started

This command installs the Opper SDK for Python using pip, the standard Python package installer. The SDK provides a convenient interface for interacting with the Opper AI API, simplifying task completion and data extraction.

```python
pip install opperai
```

--------------------------------

### Extract Structured Data with Opper Python SDK

Source: https://docs.opper.ai/overview/getting-started

This Python example demonstrates how to use the Opper SDK to extract structured data from text, specifically room descriptions. It leverages Pydantic for defining the output schema and authenticates using the `OPPER_API_KEY` environment variable. The `opper.call` method is used to send instructions and input text to the Opper AI platform, receiving a structured JSON payload as output.

```python
from opperai import Opper
# Our SDK supports Pydantic to provide structured output
from pydantic import BaseModel
import os

# Define the output structure
class RoomDescription(BaseModel):
    room_count: int
    view: str
    bed_size: str
    hotel_name: str

def main():
    opper = Opper(http_bearer=os.getenv("OPPER_API_KEY"))

    # Complete a task
    completion = opper.call(
        name="extractRoom",
        instructions="Extract details about the room from the provided text",
        input="The Grand Hotel offers a luxurious suite with 3 spacious rooms, each providing a breathtaking view of the ocean. The suite includes a king-sized bed, an en-suite bathroom, and a private balcony for an unforgettable stay.",
        output_schema=RoomDescription,
    )

    print(completion.json_payload)
    #{'room_count': 3, 'view': 'ocean', 'bed_size': 'king-sized', 'hotel_name': 'The Grand Hotel'}

main()
```

--------------------------------

### Configure Opper API Key Environment Variable

Source: https://docs.opper.ai/overview/getting-started

This shell command sets the `OPPER_API_KEY` environment variable, which is essential for authenticating requests to the Opper AI platform. Users should replace 'your-api-key' with their actual API key obtained from the Opper platform settings.

```shell
export OPPER_API_KEY="your-api-key"
```

--------------------------------

### Python Example: Initialize Opper Client and Create Knowledge Base

Source: https://docs.opper.ai/api-reference/knowledge/get-upload-url

This Python code snippet demonstrates how to initialize the Opper AI client using an API key from environment variables and programmatically create a new knowledge base. It sets up a unique name for the knowledge base based on the current timestamp and specifies an embedding model.

```Python
import os
import time
import requests
from opperai import Opper

# Initialize Opper client using your API key
opper = Opper(http_bearer=os.getenv("OPPER_API_KEY"))

# Step 1: Create a new knowledge base
unique_name = f"document_library_{int(time.time())}"
knowledge_base = opper.knowledge.create(
    name=unique_name,
    embedding_model="azure/text-embedding-3-large"
)

print(f"Created knowledge base: {knowledge_base.name}")
print(f"Knowledge base ID: {knowledge_base.id}")
```

--------------------------------

### Define Few-Shot Examples for Opper AI Task

Source: https://docs.opper.ai/capabilities/calls

This Python code defines a list of few-shot examples, each containing an input (facts and a question) and an expected output (thoughts and an answer). These examples are used to guide the AI's behavior for specific scenarios, particularly when relevant facts are missing, demonstrating how the AI should respond when it cannot answer based on provided information.

```Python
examples = [{
    "input": KBQueryInput(
        facts=[
            "Jupiter is the largest planet in the Solar System.",
            "The Great Red Spot is a giant storm on Jupiter.",
            "Saturn possesses the most extensive ring system in the Solar System."
        ],
        question="How many planets are in the Solar System?"
    ),
    "output": KBQueryOutput(
        thoughts="To determine the answer, I reviewed the provided facts. The facts discuss Jupiter, its Great Red Spot, and Saturn's extensive ring system, but they do not specify how many planets are in the Solar System. Without relevant information, the question cannot be answered based on these facts alone",
        answer="The answer to the question is unknown"
    ),
}]
```

--------------------------------

### Populating Task Dataset with Few-Shot Examples in Python

Source: https://docs.opper.ai/capabilities/learning

This Python function demonstrates how to programmatically add structured input/output examples to a task dataset for few-shot learning. It defines a list of `RoomDatabaseEntry` and `RoomDescription` pairs, representing ideal task completions, and then iterates through them to populate a specified dataset using the `opper.datasets.create_entry` API. Each example includes an input, an expected output, and a descriptive comment.

```python
def add_examples(dataset_id: str):
    """Create example datasets for few-shot learning."""
    examples = [
        {
            "input": RoomDatabaseEntry(
                hotel_name="Seaside Resort",
                room_count=2,
                view="ocean",
                beds=1,
                price_per_night=250,
                amenities=["wifi", "room service", "minibar", "balcony"]
            ).model_dump(),
            "output": RoomDescription(
                description="This room at Seaside Resort features an elegant 2-room oceanfront suite with a comfortable king bed and private balcony offering stunning ocean views. Premium amenities include complimentary WiFi, personalized room service, and a well-stocked minibar. Perfect for couples seeking a romantic getaway or honeymooners looking for luxury and privacy."
            ).model_dump(),
            "comment": "Example of a luxury oceanview suite with emphasis on romantic atmosphere"
        },
        {
            "input": RoomDatabaseEntry(
                hotel_name="Mountain Lodge",
                room_count=3,
                view="mountain",
                beds=4,
                price_per_night=350,
                amenities=["wifi", "fireplace", "kitchen", "ski storage", "parking"]
            ).model_dump(),
            "output": RoomDescription(
                description="This room at Mountain Lodge features a spacious 3-room suite with 4 comfortable beds, a fully equipped kitchen, and a cozy fireplace. The breathtaking mountain views complement modern amenities like WiFi and convenient ski storage, with complimentary parking included. Ideal for families or groups of friends planning an active mountain getaway."
            ).model_dump(),
            "comment": "Example of a family-friendly mountain suite with practical amenities"
        },
        {
            "input": RoomDatabaseEntry(
                hotel_name="Urban Boutique Hotel",
                room_count=1,
                view="city",
                beds=1,
                price_per_night=150,
                amenities=["wifi", "workspace", "coffee maker", "gym access"]
            ).model_dump(),
            "output": RoomDescription(
                description="This room at Urban Boutique Hotel features a modern space with a comfortable queen bed, dedicated workspace, and spectacular city views. Amenities include complimentary high-speed WiFi, an in-room coffee maker, and access to our fitness center. Perfect for business travelers who need a productive and convenient city-center base."
            ).model_dump(),
            "comment": "Example of a business-oriented city room with focus on productivity"
        }
    ]

    # We populate the dataset of the function with these examples
    for example in examples:
        try:
            opper.datasets.create_entry(
                dataset_id=dataset_id,
                input=str(example["input"]),
                output=str(example["output"]),
                comment=str(example["comment"])
            )
        except Exception as e:
            print(f"Error adding example: {e}")
```

--------------------------------

### Setup Opper AI Function for Room Description Generation

Source: https://docs.opper.ai/capabilities/learning

This Python function `setup_function` demonstrates how to create or retrieve an AI function using the `opper.functions` API. It defines a function named 'generate_room_description' with `RoomDatabaseEntry` as its input schema and `RoomDescription` as its output schema. It also configures few-shot learning by setting `invocation.few_shot.count` to 3, which helps the AI generate consistent outputs by pulling semantically relevant examples.

```python
def setup_function():
    """Setup and return the room description function."""
    try:
        # Create the function
        function = opper.functions.create(
            name="generate_room_description",
            instructions="Given a room database entry, describe the room in a way that is easy to understand and use for a customer.",
            input_schema=RoomDatabaseEntry.model_json_schema(),
            output_schema=RoomDescription.model_json_schema(),
            configuration={
                "invocation.few_shot.count": 3
            }
        )

    except Exception as e:
        print(f"Error creating function: {e}")
        # If function already exists, we can get it by name
        function = opper.functions.get(function_id="26ac858f-56a8-436a-9221-f100493dffda")

    return function
```

--------------------------------

### Initialize Opper AI SDK and Create Function in Python

Source: https://docs.opper.ai/api-reference/traces/get-trace-with-spans

This Python example demonstrates how to initialize the Opper AI SDK using an API key and then create a new function. It sets up a unique function name and defines its description, instructions, and the underlying model to be used.

```Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a function and call it to generate a trace
unique_name = f"research_assistant_{int(time.time())}"
created_function = opper.functions.create(
    name=unique_name,
    description="Research assistant that provides detailed analysis",
    instructions="You are a research assistant. Provide detailed, well-researched answers with multiple perspectives and cite your reasoning process.",
    model="openai/gpt-4o-mini",
)

print(f"Created function: {created_function.name}")
```

--------------------------------

### Opper API: GET /functions Endpoint Documentation

Source: https://docs.opper.ai/api-reference/functions/list-functions

This section details the `GET /functions` API endpoint for retrieving a list of functions in the current project. It specifies the required authorization, available query parameters for filtering and pagination, and the structure of a successful response, including example data.

```APIDOC
GET /functions
  Description: List existing functions with the most recent revision in the current project.

  Authorizations:
    Authorization: string (header, required)
      Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

  Query Parameters:
    name: string | null
      Description: Filter functions by name.
      Examples: "my-function", "my-namespace.my-sub-function", "my-namespace/my-sub-function"
    sort: string | null
      Description: Sort the functions by name or created_at, use '-' to sort in descending order.
      Default: "name"
      Examples: "name", "-name", "created", "-created"
    offset: integer | null
      Description: The offset of the page of functions to return when paginating.
      Default: 0
      Required range: x >= 0
    limit: integer | null
      Description: The number of functions to return per page when paginating.
      Default: 20
      Required range: 1 <= x <= 100

  Responses:
    200 OK (application/json)
      Description: Successful Response
      Type: object
      Example:
        {
          "meta": {
            "total_count": 1
          },
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "name": "my-function",
              "description": "<string>",
              "instructions": "<string>",
              "model": [
                "openai/gpt-4o",
                "openai/gpt-4o-mini"
              ],
              "revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          ]
        }
    400 Bad Request
    401 Unauthorized
    404 Not Found
    422 Unprocessable Entity
```

--------------------------------

### Define and Execute a Knowledge Base Query Task with Opper API

Source: https://docs.opper.ai/capabilities/calls

This Python example demonstrates how to define a structured task using Pydantic models for input and output schemas, and then execute it via the Opper API. It illustrates setting up a knowledge base query task with specific instructions and providing input facts to get a structured answer.

```Python
from opperai import Opper
import os
from pydantic import BaseModel, Field
from typing import List

opper = Opper(http_bearer=os.getenv("OPPER_API_KEY", ""))

# Input schema with field descriptions
class KBQueryInput(BaseModel):
    facts: List[str] = Field(description="Standalone facts to answer from")
    question: str = Field(description="The question to answer")

# Output schema with field descriptions
class KBQueryOutput(BaseModel):
    thoughts: str = Field(description="Elaborate step-by-step reasoning")
    answer: str = Field(description="Concise answer to the question")

# Task definition and completion run
response = opper.call(
    name="mini_kb_query",
    instructions="Given the list of bullet-point facts, answer the question.",
    input_schema=KBQueryInput,
    output_schema=KBQueryOutput,
    input={
        "facts": [
            "Jupiter is the largest planet in the Solar System.",
            "The Great Red Spot is a giant storm on Jupiter.",
            "Saturn possesses the most extensive ring system in the Solar System."
        ],
        "question": "Which planet hosts the Great Red Spot?"
    },
)

print(response.json_payload)
```

--------------------------------

### Example Output of Opper.ai Task Completion

Source: https://docs.opper.ai/capabilities/indexes

This JSON snippet shows an example of the structured output generated by the `opper.call` task completion, including the AI's thoughts, a suggested message for the support agent, and references to relevant ticket IDs.

```JSON
{
    'thoughts': "The user's issue seems similar to a previous ticket where the problem involved login errors and resetting credentials. It would be prudent to verify the user's identity and consider backend credential resetting, as was effective in the past case.",
    'message': "Based on a similar past ticket, this issue might be resolved by verifying the user's identity and resetting their credentials at the backend. Once complete, guide the user to attempt logging in with the new credentials.",
    'reference_ticket_ids': [123]
}
```

--------------------------------

### Example AI Task Completion Response (JSON)

Source: https://docs.opper.ai/capabilities/learning

This JSON block represents an example response from an AI task completion. It shows a generated textual description for a room, illustrating the kind of output expected from an AI function that processes structured input and produces descriptive text.

```JSON
{
    "description": "This room at The Grand Hotel offers a spacious 3-room suite with 2 comfortable beds and breathtaking ocean views. Guests can enjoy modern amenities such as complimentary WiFi, a delicious breakfast to start the day, and convenient on-site parking. Perfect for families or couples seeking a relaxing seaside retreat at an affordable rate."
}
```

--------------------------------

### Example JSON Response for Get Dataset Entry

Source: https://docs.opper.ai/api-reference/datasets/get-dataset-entry

This JSON snippet provides an example of the successful response body returned by the Opper API when retrieving a dataset entry. It includes fields such as id, input, output, expected, and comment.

```JSON
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "input": "Given this input, what is the output?",
  "output": "This is the output to the dataset entry",
  "expected": "This `was` the output to the dataset entry",
  "comment": "This is an example of how one can edit the output"
}
```

--------------------------------

### Python Example: Get Function By Name

Source: https://docs.opper.ai/api-reference/functions/get-function-by-name

This Python code snippet demonstrates how to make a GET request to the Opper API to retrieve a function by its name. It uses the `requests` library to send the HTTP request with the necessary authorization header and prints the API's response.

```Python
import requests

url = "https://api.opper.ai/v2/functions/by-name/{name}"

headers = {"Authorization": "Bearer <token>"}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

--------------------------------

### Main Execution Block for Opper AI Function Setup

Source: https://docs.opper.ai/capabilities/learning

This standard Python `main` block calls the `setup_function` to initialize the Opper AI function when the script is executed directly. It ensures that the function is set up before any further operations might be performed, providing a clear entry point for the script.

```python
def main():
    function = setup_function()

if __name__ == "__main__":
    main()
```

--------------------------------

### Opper Observability API: Get Span Endpoint Reference

Source: https://docs.opper.ai/api-reference/spans/get-span

This API documentation details the `GET /spans/{span_id}` endpoint, which is used to retrieve a specific observability span. It specifies the required `Bearer` token for authorization, the `span_id` path parameter, and the structure of the successful JSON response. An example JSON response body is provided to illustrate the expected data format for a retrieved span.

```APIDOC
GET /spans/{span_id}

Authorization:
  - Type: Bearer authentication
  - Location: header
  - Required: Yes
  - Format: `Bearer <token>`

Path Parameters:
  - span_id:
    - Type: string
    - Required: Yes
    - Description: The ID of the span to get

Responses:
  - 200 OK:
    - Description: Successful Response
    - Content-Type: application/json
    - Body Structure: object
    - Example:
      {
        "name": "my span",
        "start_time": "2024-03-20T10:00:00+00:00",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "trace_id": "123e4567-e89b-12d3-a456-426614174000",
        "parent_id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "email_tool",
        "end_time": "2024-03-20T10:00:10+00:00",
        "input": "<any>",
        "output": "<any>",
        "error": "Exception: This is an error message",
        "meta": {
          "key": "value"
        },
        "score": 10
      }
```

--------------------------------

### Python Opper AI SDK: Create Function and Manage Dataset Entries

Source: https://docs.opper.ai/api-reference/datasets/get-dataset-entries

This Python code demonstrates how to initialize the Opper AI SDK, create a new AI function with a specified model and instructions, and then populate its associated dataset with example input/output pairs. It also shows how to list existing dataset entries with pagination.

```Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a function and add some entries to get a dataset with data
unique_name = f"science_qa_{int(time.time())}"
created_function = opper.functions.create(
    name=unique_name,
    description="Science question answering assistant",
    instructions="Answer science questions clearly and accurately with helpful explanations.",
    model="openai/gpt-4o-mini",
)

print(f"Created function with dataset ID: {created_function.dataset_id}")

# Add a few entries to the dataset
opper.datasets.create_entry(
    dataset_id=created_function.dataset_id,
    input="What is photosynthesis?",
    output="Photosynthesis is the process by which plants convert sunlight, carbon dioxide, and water into glucose and oxygen.",
    expected="Photosynthesis is the biological process that converts light energy into chemical energy in plants.",
)

opper.datasets.create_entry(
    dataset_id=created_function.dataset_id,
    input="What is gravity?",
    output="Gravity is the force that attracts objects toward each other, with larger objects having stronger gravitational pull.",
    expected="Gravity is a fundamental force of attraction between masses.",
)

# List dataset entries with pagination
entries = opper.datasets.list_entries(
    dataset_id=created_function.dataset_id, offset=0, limit=10
)

print(f"Total entries: {entries.meta.total_count}")
for entry in entries.data:
    print(f"Entry {entry.id}: {entry.input[:50]}...")
    print(f"  Output: {entry.output[:50]}...")
```

--------------------------------

### Example JSON Response for Get Function By Name

Source: https://docs.opper.ai/api-reference/functions/get-function-by-name

This JSON object represents a typical successful response when retrieving a function by name from the Opper API. It includes details such as the function's name, description, instructions, input/output schemas, model configuration, and unique identifiers.

```JSON
{
  "name": "my-function",
  "description": "This function is used to add two numbers and return the result.",
  "instructions": "You are a calculator that adds two numbers and returns the result.",
  "input_schema": {
    "properties": {
      "x": {
        "title": "X",
        "type": "integer"
      },
      "y": {
        "title": "Y",
        "type": "integer"
      }
    },
    "required": [
      "x",
      "y"
    ],
    "title": "OpperInputExample",
    "type": "object"
  },
  "output_schema": {
    "properties": {
      "sum": {
        "title": "Sum",
        "type": "integer"
      }
    },
    "required": [
      "sum"
    ],
    "title": "OpperOutputExample",
    "type": "object"
  },
  "model": {
    "extra_headers": {},
    "name": "openai/gpt-4o-mini",
    "options": {
      "temperature": 0.5
    }
  },
  "configuration": {
    "beta.evaluation.enabled": true,
    "invocation.cache.ttl": 0,
    "invocation.few_shot.count": 0,
    "invocation.structured_generation.max_attempts": 5
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

--------------------------------

### Create, Add Data, and Query Opper AI Knowledge Base (Python)

Source: https://docs.opper.ai/api-reference/knowledge/query-knowledge-base

This comprehensive Python example demonstrates a full workflow for managing an Opper AI knowledge base. It covers initializing the Opper client, programmatically creating a new knowledge base, adding multiple documents with custom metadata, and subsequently querying the populated knowledge base for relevant information.

```Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a knowledge base
unique_name = f"company_policies_{int(time.time())}"
knowledge_base = opper.knowledge.create_base(
    name=unique_name, embedding_model="azure/text-embedding-3-large"
)

print(f"Created knowledge base: {knowledge_base.name}")
print(f"Knowledge base ID: {knowledge_base.id}")

# Add some HR policy documents to query against
hr_documents = [
    {
        "key": "vacation_policy_2024",
        "content": "Our company offers 25 days of paid vacation annually. Employees can carry over up to 5 unused days to the next year. Vacation requests must be submitted at least 2 weeks in advance through the HR portal.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-15"
        }
    },
    {
        "key": "sick_leave_policy",
        "content": "Employees are entitled to 12 days of paid sick leave per year. Sick leave does not carry over to the next year. Medical documentation may be required for absences longer than 3 consecutive days.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-10"
        }
    },
    {
        "key": "remote_work_policy",
        "content": "Employees may work remotely up to 3 days per week with manager approval. Remote work requests should be submitted one week in advance. All remote work must maintain productivity standards.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-02-01"
        }
    }
]

for doc in hr_documents:
    opper.knowledge.add_data(
        index_id=knowledge_base.id,
        content=doc["content"],
        key=doc["key"],
        metadata=doc["metadata"]
    )

print("Added HR policy documents to knowledge base")

# Query the knowledge base for relevant documents
results = opper.knowledge.query(
    index_id=knowledge_base.id,
    query="What are the company's vacation policies?",
    top_k=5,
    prefilter_limit=20,
    filters=[
        {"field": "category", "operation": "=", "value": "hr_policies"},
        {"field": "department", "operation": "in", "value": ["hr", "legal"]}
    ],
    rerank=True,
)

print(f"Found {len(results)} relevant documents:")
for result in results:
    print(f"Document: {result.key}")
    print(f"Score: {result.score:.3f}")
    print(f"Content: {result.content[:200]}...")
    print(f"Metadata: {result.metadata}")
    print("---")
```

--------------------------------

### Example Opper AI Metric Object Response Structure

Source: https://docs.opper.ai/api-reference/span-metrics/get-metric

This JSON snippet provides an example of the data structure returned by the Opper AI API when retrieving a metric. It outlines the key fields associated with a metric object, including its unique identifier, the ID of the span it belongs to, the dimension it measures, its numerical value, an optional comment, and the timestamp of its creation.

```json
{
  "dimension": "<string>",
  "value": 123,
  "comment": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "span_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z"
}
```

--------------------------------

### Manage Opper AI Functions and Datasets with Python

Source: https://docs.opper.ai/api-reference/datasets/list-dataset-entries

This Python snippet demonstrates the core workflow for using the Opper AI SDK. It initializes the client, creates a new function with a unique name and description, then populates its associated dataset with example question-answer pairs. Finally, it shows how to list entries from the created dataset, including pagination.

```Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a function and add some entries to get a dataset with data
unique_name = f"science_qa_{int(time.time())}"
created_function = opper.functions.create(
    name=unique_name,
    description="Science question answering assistant",
    instructions="Answer science questions clearly and accurately with helpful explanations.",
    model="openai/gpt-4o-mini",
)

print(f"Created function with dataset ID: {created_function.dataset_id}")

# Add a few entries to the dataset
opper.datasets.create_entry(
    dataset_id=created_function.dataset_id,
    input="What is photosynthesis?",
    output="Photosynthesis is the process by which plants convert sunlight, carbon dioxide, and water into glucose and oxygen.",
    expected="Photosynthesis is the biological process that converts light energy into chemical energy in plants.",
)

opper.datasets.create_entry(
    dataset_id=created_function.dataset_id,
    input="What is gravity?",
    output="Gravity is the force that attracts objects toward each other, with larger objects having stronger gravitational pull.",
    expected="Gravity is a fundamental force of attraction between masses.",
)

# List dataset entries with pagination
entries = opper.datasets.list_entries(
    dataset_id=created_function.dataset_id, offset=0, limit=10
)

print(f"Total entries: {entries.meta.total_count}")
for entry in entries.data:
    print(f"Entry {entry.id}: {entry.input[:50]}...")
    print(f"  Output: {entry.output[:50]}...")
```

--------------------------------

### Deploy and Index Documentation with Opper AI Web Indexer

Source: https://docs.opper.ai/guides/index-docs-using-github-actions

Illustrates a GitHub Actions workflow that first builds and deploys a documentation site, then uses the Opper AI Web Indexer Action to scrape and index the deployed content. This ensures the final rendered HTML, rather than source files, is indexed.

```yaml
name: Deploy and Index Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build documentation site
        run: |
          # Your build steps here
          npm install
          npm run build-docs

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

  index-website:
    needs: build-and-deploy
    runs-on: ubuntu-latest
    steps:
      - name: Index deployed documentation
        uses: opper-ai/opper-web-indexer-action@v1
        with:
          apikey: ${{ secrets.OPPER_API_KEY }}
          index: 'docs-website'
          url: 'https://yourusername.github.io/your-docs-site/'
```

--------------------------------

### Python Example: List Function Revisions

Source: https://docs.opper.ai/api-reference/functions/list-function-revisions

This Python code snippet demonstrates how to make a GET request to the Opper API to retrieve a list of function revisions for a given function ID. It uses the `requests` library and includes placeholder for authorization token.

```Python
import requests

url = "https://api.opper.ai/v2/functions/{function_id}/revisions"

headers = {"Authorization": "Bearer <token>"}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

--------------------------------

### API Reference: GET /datasets/{dataset_id}/entries

Source: https://docs.opper.ai/api-reference/datasets/list-dataset-entries

Comprehensive API documentation for retrieving a paginated list of dataset entries. This includes details on authorization, path parameters, query parameters for pagination, and an example success response structure, along with common error codes.

```APIDOC
GET /datasets/{dataset_id}/entries

Description: Retrieves a paginated list of dataset entries for a given dataset ID.

Authorizations:
  - Authorization: string (header, required)
    Description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

Path Parameters:
  - dataset_id: string (required)
    Description: The ID of the dataset.

Query Parameters:
  - offset: integer (default: 0)
    Description: The offset of the entries to get.
    Constraints: x >= 0
  - limit: integer (default: 100)
    Description: The limit of the entries to get.
    Constraints: 1 <= x <= 100

Responses:
  - 200 OK:
    Content: application/json
    Example:
      {
        "meta": {
          "total_count": 1
        },
        "data": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "input": "Given this input, what is the output?",
            "output": "This is the output to the dataset entry",
            "expected": "This `was` the output to the dataset entry",
            "comment": "This is an example of how one can edit the output"
          }
        ]
      }
  - 400 Bad Request
  - 401 Unauthorized
  - 404 Not Found
  - 422 Unprocessable Entity
```

--------------------------------

### Query Opper Dataset Entries with Python SDK

Source: https://docs.opper.ai/api-reference/datasets/query-dataset-entries

This Python example demonstrates how to initialize the Opper SDK, create a new dataset (referred to as a 'function' in the SDK context), add multiple input/output entries to it, and then query those entries based on similarity. It showcases the full workflow from dataset creation to querying, including printing the results.

```python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a function and add some geography entries to query
unique_name = f"european_geography_{int(time.time())}"
created_function = opper.functions.create(
    name=unique_name,
    description="Expert in European geography and capital cities",
    instructions="Provide accurate information about European countries and their capitals.",
    model="openai/gpt-4o-mini",
)

print(f"Created function with dataset ID: {created_function.dataset_id}")

# Add some European capital entries to make the query meaningful
entries_to_add = [
    ("What is the capital of France?", "The capital of France is Paris."),
    ("What is the capital of Germany?", "The capital of Germany is Berlin."),
    ("What is the capital of Italy?", "The capital of Italy is Rome."),
    ("What is the capital of Spain?", "The capital of Spain is Madrid."),
    ("What is the capital of Portugal?", "The capital of Portugal is Lisbon."),
]

for input_text, output_text in entries_to_add:
    opper.datasets.create_entry(
        dataset_id=created_function.dataset_id, input=input_text, output=output_text
    )

print("Added European capital entries to dataset")

# Query dataset entries by similarity
entries = opper.datasets.query_entries(
    dataset_id=created_function.dataset_id, query="capital cities of Europe", limit=5
)

print(f"Found {len(entries)} similar entries:")
for entry in entries:
    print(f"Entry {entry.id}: {entry.input}")
    print(f"  Output: {entry.output}")
    print("---")
```

--------------------------------

### Python: Initialize Opper Client and Create Knowledge Base

Source: https://docs.opper.ai/api-reference/knowledge/get-upload-url

This Python snippet demonstrates how to initialize the Opper AI client using an API key from environment variables and then create a new knowledge base. It assigns a unique name to the knowledge base based on the current timestamp and specifies the embedding model to be used.

```python
import os
import time
import requests
from opperai import Opper

# Initialize Opper client using your API key
opper = Opper(http_bearer=os.getenv("OPPER_API_KEY"))

# Step 1: Create a new knowledge base
unique_name = f"document_library_{int(time.time())}"
knowledge_base = opper.knowledge.create(
    name=unique_name,
    embedding_model="azure/text-embedding-3-large"
)

print(f"Created knowledge base: {knowledge_base.name}")
print(f"Knowledge base ID: {knowledge_base.id}")
```

--------------------------------

### List Language Models using Opper Python Client

Source: https://docs.opper.ai/api-reference/models/list-models

This Python code demonstrates how to initialize the Opper client with an API key and then list all available language models. It iterates through the retrieved models to display their names, providers, locations, and associated costs. The example also shows how to filter models by a specific hosting provider like 'openai'.

```Python
from opperai import Opper

opper = Opper(http_bearer="YOUR_API_KEY")

# List all available language models
models = opper.language_models.list(offset=0, limit=50)

print(f"Total models available: {models.meta.total_count}")
print(f"Showing {len(models.data)} models:")
print("=" * 60)

for model in models.data:
    print(f"Model: {model.name}")
    print(f"  Provider: {model.hosting_provider}")
    print(f"  Location: {model.location}")
    if model.input_cost_per_token:
        print(f"  Input cost: ${model.input_cost_per_token:.6f} per token")
    if model.output_cost_per_token:
        print(f"  Output cost: ${model.output_cost_per_token:.6f} per token")
    print("---")

# Filter for specific provider
openai_models = [m for m in models.data if "openai" in m.hosting_provider.lower()]
print(f"\nFound {len(openai_models)} OpenAI models:")
for model in openai_models[:5]:  # Show first 5
    print(f"- {model.name}")
```

--------------------------------

### Extend Schema with Regex Patterns for Content Enforcement

Source: https://docs.opper.ai/capabilities/calls

Illustrates how to use regex patterns within a Pydantic `BaseModel` schema to enforce specific content formats for string fields. This example ensures the 'answer' field starts with a predefined phrase, providing strict output validation.

```Python
class KBQueryOutput(BaseModel):
    thoughts: str = Field(
        description="Elaborate step-by-step reasoning"
    )
    answer: str = Field(
        description="Concise answer to the question starting with 'The answer to the question is '",
        pattern=r"^The answer to the question is [A-Za-z0-9\s]+$"
    )
```

```TypeScript
class KBQueryOutput(BaseModel):
    thoughts: str = Field(
        description="Elaborate step-by-step reasoning"
    )
    answer: str = Field(
        description="Concise answer to the question starting with 'The answer to the question is '",
        pattern=r"^The answer to the question is [A-Za-z0-9\s]+$"
    )
```

--------------------------------

### Transcribe Audio Files with Opper AI in Python

Source: https://docs.opper.ai/patterns/multimodal

This code snippet demonstrates how to use the Opper AI SDK in Python to transcribe an audio file. It involves reading an MP3 file, encoding it to base64, and then calling the Opper API with specific instructions and a model to get the transcription. The example includes a main block for direct execution.

```Python
import base64
import os

from opperai import Opper

opper = Opper(
    http_bearer=os.getenv("OPPER_API_KEY"),
)

def transcribe_audio(path: str):
    media_input = f"data:audio/mp3;base64,{base64.b64encode(open(path, 'rb').read()).decode('utf-8')}"
    response = opper.call(
        name="transcribe_audio",
        instructions="given an audio file, return the transcription of the audio",
        input={
            "_opper_media_input": media_input,  # this field name is required by opper
        },
        model="gcp/gemini-2.5-pro",
    )
    return response.message

if __name__ == "__main__":
    audio_path = "sample.mp3"
    transcription = transcribe_audio(audio_path)
    print(transcription)
```

--------------------------------

### Python SDK Example: Create and Add Data to Opper Knowledge Base

Source: https://docs.opper.ai/api-reference/knowledge/query-knowledge-base

This Python code snippet demonstrates how to initialize the Opper SDK, create a new knowledge base with a unique name and specified embedding model, and then add multiple HR policy documents to it. Each document includes content, a unique key, and relevant metadata for later retrieval.

```Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a knowledge base
unique_name = f"company_policies_{int(time.time())}"
knowledge_base = opper.knowledge.create_base(
    name=unique_name, embedding_model="azure/text-embedding-3-large"
)

print(f"Created knowledge base: {knowledge_base.name}")
print(f"Knowledge base ID: {knowledge_base.id}")

# Add some HR policy documents to query against
hr_documents = [
    {
        "key": "vacation_policy_2024",
        "content": "Our company offers 25 days of paid vacation annually. Employees can carry over up to 5 unused days to the next year. Vacation requests must be submitted at least 2 weeks in advance through the HR portal.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-15",
        },
    },
    {
        "key": "sick_leave_policy",
        "content": "Employees are entitled to 12 days of paid sick leave per year. Sick leave does not carry over to the next year. Medical documentation may be required for absences longer than 3 consecutive days.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-10",
        },
    },
    {
        "key": "remote_work_policy",
        "content": "Employees may work remotely up to 3 days per week with manager approval. Remote work requests should be submitted one week in advance. All remote work must maintain productivity standards.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-02-01",
        },
    },
]

for doc in hr_documents:
    opper.knowledge.add_data(
        index_id=knowledge_base.id,
        content=doc["content"],
        key=doc["key"],
        metadata=doc["metadata"],
    )

print("Added HR policy documents to knowledge base")
```

--------------------------------

### Retrieve Span Metric using Opper Python SDK

Source: https://docs.opper.ai/api-reference/span-metrics/get-metric

This Python example demonstrates how to use the Opper SDK to create a span, create a custom metric for that span, and then retrieve the specific metric by its ID. It showcases the full lifecycle of metric management within a span, including creating a span, adding a metric, and then fetching it.

```Python
from datetime import datetime, timezone
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a span and a metric to have real IDs to work with
created_span = opper.spans.create(
    name="customer_feedback_analysis",
    start_time=datetime.now(timezone.utc),
    type="analysis",
    input="Customer feedback: The service was excellent and the response time was very fast.",
    output="Sentiment: Positive, Key topics: service quality, response time, Overall satisfaction: High",
    meta={"analysis_type": "sentiment", "user_id": "user_123"},
)

print(f"Created span with ID: {created_span.id}")

# Create a metric to get
created_metric = opper.span_metrics.create_metric(
    span_id=created_span.id,
    dimension="sentiment_score",
    value=9.2,
    comment="Sentiment analysis score (0-10, where 10 is most positive)",
)

print(f"Created metric with ID: {created_metric.id}")

# Get the specific metric for the span
metric = opper.span_metrics.get(span_id=created_span.id, metric_id=created_metric.id)

print(f"Metric Details:")
print(f"  ID: {metric.id}")
print(f"  Span ID: {metric.span_id}")
print(f"  Dimension: {metric.dimension}")
print(f"  Value: {metric.value}")
if metric.comment:
    print(f"  Comment: {metric.comment}")
print(f"  Created: {metric.created_at}")

# Check if it's a quality metric
if "quality" in metric.dimension.lower():
    if metric.value >= 8.0:
        print("\n✅ High quality response!")
    elif metric.value >= 6.0:
        print("\n⚠️ Moderate quality response")
    else:
        print("\n❌ Low quality response - needs improvement")
```

--------------------------------

### Initialize Opper Client for Server-Side Task Creation

Source: https://docs.opper.ai/capabilities/learning

This snippet demonstrates how to initialize the Opper client using an API key for authentication. This client is essential for managing server-side task configurations, enabling centralized control over datasets and analytics for specific AI tasks within the Opper platform.

```Python
from opperai import Opper
from pydantic import BaseModel, Field
from typing import List
import os

# Initialize Opper client
opper = Opper(http_bearer=os.getenv("OPPER_API_KEY", ""))
```

--------------------------------

### Initialize Opper SDK for Custom Knowledge Indexing

Source: https://docs.opper.ai/capabilities/indexes

This Python snippet demonstrates how to initialize the Opper SDK using an API key retrieved from environment variables. It sets up the client for interacting with Opper's services, including the knowledge endpoint, enabling subsequent operations like indexing documents and performing semantic searches.

```Python
from opperai import Opper
# Our SDK supports Pydantic to provide structured output
from pydantic import BaseModel
from typing import Literal
import os

opper = Opper(http_bearer=os.getenv("OPPER_API_KEY"))
```

--------------------------------

### Python Main Function for Console Agent Command-Line Execution

Source: https://docs.opper.ai/patterns/agent

This `main` function initializes the `ConsoleAgent` and handles command-line arguments to retrieve the task. It demonstrates how to invoke the agent's `plan_and_execute` method with a user-provided task, providing usage instructions if no task is supplied.

```python
def main():
    agent = ConsoleAgent()

    # Check if task is provided as command line argument
    if len(sys.argv) < 2:
        print("Simple Console Agent")
        print("Usage: python simple_console_agent.py \"<task>\"")
        print("Example: python simple_console_agent.py \"Create a folder called 'my_project'\"")
        sys.exit(1)

    # Get task from command line argument
    task = " ".join(sys.argv[1:])
    print(f"Simple Console Agent")
    print(f"Task: {task}")
    print()

    # Execute the task
    agent.plan_and_execute(task)

if __name__ == "__main__":
    main()
```
Tokens:
Raw