AI Query Guide

Introduction to AI Query

The Wickson API's AI inferencing endpoint provides an intelligent assistant that can answer questions, generate content, and provide insights based on your data. This powerful feature allows you to interact with state of the art LLM's to obtain high-quality responses tailored to your specific needs.

What makes this feature particularly powerful is its ability to ground responses in your uploaded media content. By referencing a specific document, image, or other media item, the AI can generate answers directly based on that content's information, ensuring relevance and accuracy.

Use AI Query when you need to:

• Extract insights from your documents and media
• Generate creative content based on your data
• Get answers to questions about your specific content
• Create summaries, analyses, or explanations of your materials

Key Concepts

Media Grounding

When you provide a media_id, the AI grounds its response in that specific content. This ensures responses are based on your actual data rather than general knowledge, making answers more precise and relevant to your needs.

Temperature Control

The temperature parameter (0.0-1.0) controls how creative or deterministic the AI's responses will be:

• Lower values (0.1-0.3): More focused, deterministic, factual responses
• Medium values (0.4-0.7): Balanced responses with some creativity
• Higher values (0.8-1.0): More creative, varied responses

System Prompts

The system_prompt parameter provides special instructions to guide how the AI approaches your query. It's like giving the AI a specific role or perspective, such as "Analyze this as a financial advisor" or "Explain this in simple terms for a beginner."

Conversation Context

The context parameter allows you to maintain multi-turn conversations by providing previous exchanges. This helps the AI understand the ongoing conversation and provide contextually appropriate responses.

Working with AI Query

Basic Query Example

Python

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Create a simple query without media context
query_data = {
    "query": "What factors contribute to successful machine learning projects?",
    "temperature": 0.7,
    "max_tokens": 1024
}

# Execute query
response = requests.post(
    "https://api.wickson.ai/v1/ai/query",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=query_data
)

# Process response
if response.status_code == 200:
    data = response.json()["data"]

    # Display the AI's response
    print("AI Response:")
    print(data["response"])

    # Show usage information
    print("\nToken Usage:")
    print(f"Input tokens: {data['billing']['usage']['context_tokens']}")
    print(f"Output tokens: {data['billing']['usage']['response_tokens']}")
    print(f"Processing time: {data['billing']['usage']['processing_time_ms']}ms")
    print(f"Cost: ${data['billing']['total_cost']}")
else:
    print(f"Error {response.status_code}: {response.text}")

cURL

curl -X POST https://api.wickson.ai/v1/ai/query \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What factors contribute to successful machine learning projects?",
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Media-Grounded Query Example

Use a specific media item as context for your query:

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Create a query grounded in media content
query_data = {
    "query": "What are the key findings from this research paper?",
    "media_id": "vec-a1b2c3d4",             # Reference a specific media item
    "temperature": 0.5,                     # Lower temperature for more focused response
    "max_tokens": 1500,                     # Allow longer response for detailed analysis
    "system_prompt": "Analyze this as a research scientist and highlight the most significant discoveries"
}

# Execute query
response = requests.post(
    "https://api.wickson.ai/v1/ai/query",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=query_data
)

# Process response
if response.status_code == 200:
    data = response.json()["data"]

    # Display the AI's response
    print("AI Analysis of Research Paper:")
    print(data["response"])

    # Show media context information
    if "media_context" in data:
        print("\nAnalyzed Content:")
        print(f"Media ID: {data['media_context']['media_id']}")
        print(f"Media Type: {data['media_context']['media_type']}")
        print(f"Collection: {data['media_context']['collection']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Multi-turn Conversation Example

Maintain context across multiple interactions:

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Function to send query and update conversation
def chat_with_ai(query, conversation_history=None, media_id=None):
    # Prepare request data
    request_data = {
        "query": query,
        "temperature": 0.7
    }

    # Add conversation history if provided
    if conversation_history:
        request_data["context"] = conversation_history

    # Add media context if provided
    if media_id:
        request_data["media_id"] = media_id

    # Execute query
    response = requests.post(
        "https://api.wickson.ai/v1/ai/query",
        headers={
            "X-Api-Key": api_key,
            "Content-Type": "application/json"
        },
        json=request_data
    )

    if response.status_code != 200:
        return f"Error {response.status_code}: {response.text}", conversation_history

    # Get AI response
    ai_response = response.json()["data"]["response"]

    # Update conversation history
    new_history = ""
    if conversation_history:
        new_history = conversation_history + f"\nHuman: {query}\nAI: {ai_response}"
    else:
        new_history = f"Human: {query}\nAI: {ai_response}"

    return ai_response, new_history

# Start a conversation
conversation = None

# First message with media context
response, conversation = chat_with_ai(
    "What are the key findings in this quarterly report?",
    conversation_history=conversation,
    media_id="vec-38fn4098fn3049rj09jj9409jjjkdd"
)
print("AI:", response)

# Follow-up question without media_id (using conversation context)
response, conversation = chat_with_ai(
    "What were the biggest challenges mentioned?",
    conversation_history=conversation
)
print("AI:", response)

# Another follow-up
response, conversation = chat_with_ai(
    "Can you compare these results to industry averages?",
    conversation_history=conversation
)
print("AI:", response)

Controlling Response Style with System Prompts

System prompts help you guide the AI's approach:

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Example system prompts for different purposes
system_prompts = {
    "technical": "Respond as a technical expert with detailed, precise information using industry terminology",
    "simple": "Explain everything in simple terms that a non-expert would understand. Avoid jargon and use analogies where helpful",
    "executive": "Provide a concise executive summary focusing on business impact, risks, and strategic implications",
    "creative": "Respond in a creative, engaging manner that captures imagination and interest"
}

# Create query with selected system prompt
query_data = {
    "query": "Explain how transformer neural networks work",
    "system_prompt": system_prompts["simple"],  # Select the simple explanation style
    "temperature": 0.4  # Lower temperature for more factual response
}

# Execute query
response = requests.post(
    "https://api.wickson.ai/v1/ai/query",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=query_data
)

# Display the AI's simplified explanation
if response.status_code == 200:
    print(response.json()["data"]["response"])

Optimizing Media-Grounded Queries

Get Specific Information from a Document

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Example of extracting specific information
query_data = {
    "query": "What were the revenue figures for Q3 and how do they compare to projections?",
    "media_id": "vec-38fn4098fn3049rj09jj9409jjjkdd",  # Financial report
    "temperature": 0.3,  # Lower temperature for factual accuracy
    "system_prompt": "Extract precise financial data from the document and present it clearly"
}

# Execute query
response = requests.post(
    "https://api.wickson.ai/v1/ai/query",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=query_data
)

# Display the extracted financial information
if response.status_code == 200:
    print(response.json()["data"]["response"])

Analyze Multiple Documents in Sequence

import requests

def analyze_documents(query, document_ids, api_key):
    """Analyze multiple documents with the same query and compile results"""

    all_responses = []

    for i, doc_id in enumerate(document_ids, 1):
        # Create query for this document
        query_data = {
            "query": query,
            "media_id": doc_id,
            "temperature": 0.4
        }

        print(f"Analyzing document {i} of {len(document_ids)}...")

        # Execute query
        response = requests.post(
            "https://api.wickson.ai/v1/ai/query",
            headers={
                "X-Api-Key": api_key,
                "Content-Type": "application/json"
            },
            json=query_data
        )

        if response.status_code == 200:
            doc_response = response.json()["data"]

            # Get document metadata
            doc_info = doc_response.get("media_context", {})
            doc_name = doc_info.get("collection", f"Document {i}")

            # Store response with document info
            all_responses.append({
                "document": doc_name,
                "media_id": doc_id,
                "response": doc_response["response"]
            })
        else:
            print(f"Error analyzing document {doc_id}: {response.status_code}")

    # Compile the findings
    compilation = ""
    for i, resp in enumerate(all_responses, 1):
        compilation += f"\n\n--- {resp['document']} ---\n"
        compilation += resp['response']

    return compilation

# Example usage
api_key = "YOUR_API_KEY"
document_ids = [
    "vec-38fn4098fn3049rj09jj9409jjjkdd",
    "vec-94jf84jf84jf84jf84jf84jf84jf84",
    "vec-29dk29dk29dk29dk29dk29dk29dk29"
]

findings = analyze_documents(
    "Extract the key risk factors mentioned in this document",
    document_ids,
    api_key
)

print("\n\nCOMPILED RISK ANALYSIS ACROSS DOCUMENTS:")
print(findings)

Temperature and Creativity Control

The temperature parameter significantly affects response style. Here's a guide for selecting appropriate values:

Temperature	Response Style	Best For
0.1-0.3	Focused, factual, deterministic	Data extraction, factual Q&A, formal analysis
0.4-0.6	Balanced, moderately creative	General explanations, summaries, professional content
0.7-0.8	Creative, varied	Content generation, brainstorming, conversational responses
0.9-1.0	Highly creative, more random	Creative writing, diverse idea generation

Example of temperature comparison:

import requests

# Configuration
api_key = "YOUR_API_KEY"
query = "Write a short paragraph about the future of renewable energy"

# Test different temperatures
temperatures = [0.2, 0.5, 0.9]
results = []

for temp in temperatures:
    # Create query with this temperature
    query_data = {
        "query": query,
        "temperature": temp,
        "max_tokens": 200
    }

    # Execute query
    response = requests.post(
        "https://api.wickson.ai/v1/ai/query",
        headers={
            "X-Api-Key": api_key,
            "Content-Type": "application/json"
        },
        json=query_data
    )

    if response.status_code == 200:
        result = response.json()["data"]["response"]
        results.append((temp, result))

# Display comparison
for temp, result in results:
    print(f"\n--- Temperature: {temp} ---")
    print(result)
    print("-" * 50)

Best Practices

Crafting Effective Queries

1. Be Specific: Instead of "Tell me about this document," ask "What are the three main conclusions from this research paper?"

2. Provide Context: Include relevant details in your query to help the AI understand exactly what you're looking for.

3. One Question at a Time: For the most focused responses, ask one clear question rather than multiple questions in a single query.

4. Use System Prompts: The system_prompt parameter is powerful for guiding response style and approach without cluttering your main query.

Using Media Context Effectively

Upload Meaningful Content: Make sure the content you're referencing contains the information you need.

Direct Attention: Point the AI to specific aspects of the content in your query.

Consider Media Type: Different media types require different approaches:

• For documents, ask about textual content, arguments, or data
• For images, ask about visual elements, scene content, or composition
• For video, ask about scenes, actions, or spoken content

Verify with Follow-ups:

If you're unsure about an answer, ask follow-up questions for clarification.

Managing Conversation Context

1. Start Fresh When Needed: Begin new conversation contexts when changing topics significantly.

2. Provide Essential History: Only include relevant previous exchanges to maintain context without exceeding token limits.

3. Clear Structure: Format conversation history with clear speaker labels (e.g., "User:" and "AI:").

4. Reset Context Periodically: For very long conversations, consider starting fresh occasionally to avoid confusion.

Cost Optimization

1. Reuse Media Context: When asking multiple questions about the same content, use the same media_id to avoid reprocessing.

2. Optimize Token Usage: Keep queries concise and focused to minimize input tokens.

3. Control Response Length: Use max_tokens to limit response length for cost-predictable operations.

4. Batch Related Queries: For analysis tasks, combine related questions into a single comprehensive query when possible.

Understanding Billing

Each query has the following cost components:

• Base Fee: $0.01 per query
• Token Charges: For most standard queries, only the base fee applies. Additional token charges apply only for very large inputs or outputs.

The billing information in the response provides detailed usage statistics:

"billing": {
  "total_cost": 0.01,
  "base_fee": 0.01,
  "token_charges": 0.0,
  "usage": {
    "context_tokens": 8520,
    "response_tokens": 105,
    "total_tokens": 8625,
    "processing_time_ms": 850
  },
  "pricing_tier": "minimum"
}

This shows:

• The query cost $0.01 (just the base fee)
• It processed 8,520 input tokens and generated 105 output tokens
• Processing took 850ms
• The "minimum" pricing tier was applied (only base fee, no token charges)

Troubleshooting

Issue	Solutions
Response not based on media content	Verify the media_id is correct Make your query more specific about what to extract from the content Check if the referenced media contains the information you need
Token limit exceeded	Use shorter queries Reference smaller media files Break complex queries into multiple simpler queries
Responses too generic	Lower the temperature (try 0.3-0.5) Make your query more specific Use a more directive system prompt
Responses too creative/variable	Decrease temperature (try 0.1-0.3 for factual responses) Use system prompts that emphasize precision
Context confusion in conversations	Start fresh with a new conversation Provide clearer structure in your conversation history Be more explicit in your follow-up questions

Common Use Cases

Document Analysis and Extraction

Extract specific information from documents:

# Extract financial data
query_data = {
    "query": "What were our top 3 revenue sources last quarter and how did they change year-over-year?",
    "media_id": "vec-financial_report",
    "temperature": 0.2,
    "system_prompt": "Act as a financial analyst extracting precise data"
}

Content Summarization

Generate concise summaries of documents or other media:

# Summarize a research paper
query_data = {
    "query": "Provide a comprehensive yet concise summary of this research paper, including the methodology, key findings, and limitations",
    "media_id": "vec-research_paper",
    "temperature": 0.4,
    "max_tokens": 800
}

Creative Content Generation

Generate creative content based on specific inputs:

# Generate marketing copy
query_data = {
    "query": "Write engaging marketing copy for our new AI-powered analytics platform, emphasizing ease of use and powerful insights",
    "temperature": 0.8,
    "max_tokens": 300,
    "system_prompt": "Write as an experienced marketing copywriter with a modern, professional tone"
}

Expert Analysis

Get expert-level analysis of specific content:

# Legal document analysis
query_data = {
    "query": "Analyze this contract and identify any potential issues, unclear clauses, or areas that might need further negotiation",
    "media_id": "vec-contract_document",
    "temperature": 0.3,
    "system_prompt": "Analyze this as an experienced corporate lawyer focusing on practical risks and recommendations"
}

Educational Content

Create educational materials or explanations:

# Generate educational content
query_data = {
    "query": "Explain how neural networks work in simple terms that a high school student would understand",
    "temperature": 0.6,
    "max_tokens": 1000,
    "system_prompt": "Explain concepts in a friendly, accessible way with helpful analogies. Avoid unnecessary jargon."
}

AI Query vs. Media Analysis Endpoint

The Wickson API offers two complementary AI capabilities:

Feature	AI Query (/ai/query)	Media Analysis (/ai/analyze)
Input	Text query (with optional media_id)	Uploaded file + query
Best for	Querying already-processed media items	Analyzing new, unprocessed files
Media access	References previously uploaded and processed media	Directly analyzes newly uploaded files (but does not store info)
Use case	"Answer questions about my existing content"	"Analyze this new file I'm uploading now"

Both endpoints work together in a typical workflow:

1. Use /ai/analyze when you want to analyze a new media file
2. Use /ai/query for ongoing interaction with your processed media library or for other purposes, like general chatting, etc.