grokipedia-api 0.3.0

A Python client for accessing Grokipedia content

Grokipedia API

A Python client for accessing content from Grokipedia, an open-source, comprehensive collection of all knowledge.

Features

• Search: Search through Grokipedia's vast collection of articles
• Page Retrieval: Get full page content, including headings, text, and citations
• Structured Data: Access well-structured data with proper typing
• Easy to Use: Simple and intuitive API
• Async Support: Fast async/await API with aiohttp for concurrent operations
• Auto Retries: Automatic retry logic with exponential backoff
• Rate Limit Handling: Built-in rate limit detection and handling
• MCP Server: Model Context Protocol server for AI integrations (Python 3.10+)
• CLI Support: Command-line interface for quick access

Installation

Basic Installation

pip install grokipedia-api

With Additional Features

For async support:

pip install grokipedia-api[async]

For MCP server functionality (Python 3.10+):

pip install grokipedia-api[mcp]

For all features:

pip install grokipedia-api[all]

Or install from source:

git clone https://github.com/AkeBoss-tech/grokipedia-api.git
cd grokipedia-api
pip install -e .

Quick Start

Basic Usage

from grokipedia_api import GrokipediaClient

# Create a client
client = GrokipediaClient()

# Search for articles
results = client.search("Python programming")
print(f"Found {len(results['results'])} results")

# Get a specific page
page = client.get_page("United_Petroleum")
print(f"Title: {page['page']['title']}")
print(f"Content: {page['page']['content'][:200]}...")

Search Functionality

from grokipedia_api import GrokipediaClient

client = GrokipediaClient()

# Search with pagination
results = client.search("machine learning", limit=20, offset=0)
for result in results['results']:
    print(f"- {result['title']}")
    print(f"  Slug: {result['slug']}")
    print(f"  Views: {result['viewCount']}")
    print()

Get Full Page Content

from grokipedia_api import GrokipediaClient

client = GrokipediaClient()

# Get full page with all content
page = client.get_page("United_Petroleum", include_content=True)

# Access structured data
title = page['page']['title']
content = page['page']['content']
citations = page['page']['citations']

print(f"Article: {title}")
print(f"\nCitations: {len(citations)}")
for citation in citations:
    print(f"- [{citation['id']}] {citation['title']}")
    print(f"  {citation['url']}")

Async Usage

For faster, concurrent operations with async/await:

import asyncio
from grokipedia_api import AsyncGrokipediaClient, search_many, get_many_pages

async def main():
    # Basic async usage
    async with AsyncGrokipediaClient() as client:
        results = await client.search("Python programming")
        print(f"Found {len(results['results'])} results")
        
        page = await client.get_page("United_Petroleum")
        print(f"Title: {page['page']['title']}")
    
    # Search multiple queries concurrently
    queries = ["Python", "JavaScript", "Rust"]
    all_results = await search_many(queries, limit=5)
    print(f"Total results: {len(all_results)}")
    
    # Get multiple pages concurrently
    slugs = ["United_Petroleum", "Python_(programming_language)"]
    pages = await get_many_pages(slugs)
    for page_data in pages:
        print(f"✓ {page_data['page']['title']}")

asyncio.run(main())

Automatic Retries

The client automatically retries failed requests with exponential backoff:

from grokipedia_api import GrokipediaClient

client = GrokipediaClient()

# Automatically retries up to 3 times on network errors
results = client.search("machine learning")

Using Context Manager

from grokipedia_api import GrokipediaClient

# Use context manager for automatic cleanup
with GrokipediaClient() as client:
    results = client.search("Python")
    for result in results['results']:
        print(result['title'])

MCP Server (Python 3.10+)

For AI agent integrations:

# Start the MCP server
grokipedia-mcp

The server exposes tools for searching and retrieving Grokipedia content via the Model Context Protocol. See MCP_SERVER.md for detailed documentation.

Command Line Interface

# Search for articles
grokipedia search "Python programming"

# Get a specific page
grokipedia get "United_Petroleum" --citations

# Get full content
grokipedia get "United_Petroleum" --full

API Reference

GrokipediaClient

The main client class for interacting with Grokipedia.

Methods

search(query, limit=12, offset=0)

Search for articles in Grokipedia.

Parameters:

• query (str): Search query string
• limit (int): Maximum number of results to return (default: 12)
• offset (int): Number of results to skip for pagination (default: 0)

Returns:

• Dictionary containing:
  • results: List of search result dictionaries
  • total_count: Total number of results (if available)

Example:

results = client.search("Python programming", limit=20)

get_page(slug, include_content=True, validate_links=True)

Get a specific page by its slug.

Parameters:

• slug (str): Page slug (e.g., "United_Petroleum")
• include_content (bool): Whether to include full content (default: True)
• validate_links (bool): Whether to validate links (default: True)

Returns:

• Dictionary containing:
  • page: Page information including title, content, citations, images, etc.
  • found: Boolean indicating if the page was found

Example:

page = client.get_page("Python_(programming_language)")

search_pages(query, limit=12)

Search for pages and return results as a list.

Parameters:

• query (str): Search query string
• limit (int): Maximum number of results to return (default: 12)

Returns:

• List of search result dictionaries

Example:

pages = client.search_pages("machine learning")

Data Models

The library provides structured data models for working with Grokipedia content:

• Page: Represents a full Grokipedia page
• Citation: Represents a citation in an article
• Image: Represents an image in an article
• SearchResult: Represents a search result

Error Handling

The library provides custom exceptions:

• GrokipediaError: Base exception for all Grokipedia errors
• GrokipediaNotFoundError: Raised when a requested resource is not found
• GrokipediaAPIError: Raised when there's an API-related error

from grokipedia_api import GrokipediaClient
from grokipedia_api.exceptions import GrokipediaNotFoundError

client = GrokipediaClient()

try:
    page = client.get_page("NonExistentPage")
except GrokipediaNotFoundError:
    print("Page not found!")

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/AkeBoss-tech/grokipedia-api.git
cd grokipedia-api

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=grokipedia_api --cov-report=html

Code Style

This project uses:

• Black for code formatting
• Ruff for linting
• mypy for type checking

# Format code
black grokipedia_api tests

# Lint code
ruff check grokipedia_api tests

# Type check
mypy grokipedia_api

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Grokipedia for providing the amazing knowledge base
• All the contributors and maintainers

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Changelog

0.1.0 (2025-01-09)

• Initial release
• Search functionality
• Page retrieval with full content
• Structured data models
• Basic error handling