API_README.md

Groqqle API Guide for Developers

This guide demonstrates how to use Groqqle's API functionalities for developers without the GUI interface.

Overview

Groqqle offers two main approaches for developers to integrate search capabilities into their applications:

1. HTTP REST API: Start Groqqle in API mode and make HTTP requests to it
2. Direct Python Integration: Use the Groqqle_web_tool class in your Python code

Method 1: Using the HTTP REST API

Starting the API Server

To use Groqqle's API server, run:

python Groqqle.py api --num_results 20 --max_tokens 4096

The API server will start running on http://127.0.0.1:5000.

Making API Requests

You can send POST requests to the /search endpoint with the following parameters:

{
  "query": "your search query",
  "num_results": 20,
  "max_tokens": 4096,
  "search_type": "web"  // Use "web" for web search or "news" for news search
}

Python Example

import requests
import json

def groqqle_search(query, search_type="web", num_results=10, max_tokens=4096):
    """Function to perform a search using Groqqle's API."""
    api_url = "http://127.0.0.1:5000/search"
    
    payload = {
        "query": query,
        "num_results": num_results,
        "max_tokens": max_tokens,
        "search_type": search_type  # "web" or "news"
    }
    
    response = requests.post(api_url, json=payload)
    response.raise_for_status()
    return response.json()

# Example usage
results = groqqle_search("quantum computing breakthroughs", search_type="web")
for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Description: {result['description'][:100]}...")
    print("")

Response Format

The API returns a JSON array of results, each containing:

• title: The title of the webpage or article
• url: The URL of the result
• description: A brief description or snippet
• source and timestamp: (for news results only)

Method 2: Direct Python Integration

You can integrate Groqqle directly into your Python applications without starting a separate server by using the Groqqle_web_tool class.

Basic Usage

from Groqqle_web_tool import Groqqle_web_tool

# Initialize the tool with your API key and configuration
groqqle_tool = Groqqle_web_tool(
    api_key='your_groq_api_key_here',
    provider_name='groq',  # Can also use 'anthropic' if configured
    num_results=10,        # Number of search results to return
    max_tokens=4096,       # Max tokens for AI responses
    model='llama3-8b-8192', # Model to use
    temperature=0.0,        # Temperature setting for generation
    comprehension_grade=8   # Target reading level (1-15)
)

# Perform a web search
query = 'latest advancements in artificial intelligence'
results = groqqle_tool.run(query)

# Process the search results
for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Description: {result['description']}")
    print("")

URL Summarization

You can also generate summaries of web content:

# Summarize content from a specific URL
url = "https://example.com/article"
summary = groqqle_tool.summarize_url(url)

print("URL Summary:")
print(f"Title: {summary['title']}")
print(f"Description: {summary['description']}")

Integration with AI Assistants

For integrating with PocketGroq and other LLM systems:

from pocketgroq import GroqProvider
from Groqqle_web_tool import Groqqle_web_tool

# Set up the provider and tool
groq_provider = GroqProvider(api_key='your_groq_api_key_here')
groqqle_tool = Groqqle_web_tool(api_key='your_groq_api_key_here')

# Define the tool for PocketGroq
tools = [
    {
        "type": "function",
        "function": {
            "name": "groqqle_web_search",
            "description": "Perform a web search using Groqqle",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

def groqqle_web_search(query):
    results = groqqle_tool.run(query)
    return results

# Use the tool in your project
user_message = "Search for the latest developments in quantum computing"
system_message = "You are a helpful assistant. Use the Groqqle web search tool to find information."

response = groq_provider.generate(
    system_message,
    user_message,
    tools=tools,
    tool_choice="auto"
)

print(response)

Setup and Configuration

Environment Variables

Create a .env file in your project root or set environment variables:

GROQ_API_KEY=your_groq_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here  # Optional, if using Anthropic

Required Dependencies

For proper functionality, install these dependencies:

pip install -r requirements.txt

Key dependencies include:

1. requests - For HTTP requests
2. beautifulsoup4 - For parsing HTML
3. python-dotenv - For loading environment variables
4. groq - For Groq API integration
5. selenium & webdriver-manager - For web search functionality

Troubleshooting

If you encounter issues with the web search functionality in cloud environments, see the TROUBLESHOOTING.md file for detailed guidance. Common issues include:

1. Missing API keys
2. Browser dependencies in cloud environments
3. Installation of required packages

Configuration Options

All methods support these configuration options:

• num_results: Number of search results to return (default: 10)
• max_tokens: Maximum tokens for AI responses (default: 4096)
• model: Model to use (default: "llama3-8b-8192")
• temperature: Temperature for generation (default: 0.0)
• comprehension_grade: Target reading comprehension level (default: 8)

Security Notes

• Never expose your API keys in client-side code
• Consider rate limiting to prevent abuse of your search functionality
• Validate user input before passing to search functions