Metadata-Version: 2.4
Name: grokipedia-api
Version: 0.1.0
Summary: A Python client for accessing Grokipedia content
Author-email: Akash Dubey <akashdub06@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AkeBoss-tech/grokipedia-api
Project-URL: Documentation, https://github.com/AkeBoss-tech/grokipedia-api
Project-URL: Repository, https://github.com/AkeBoss-tech/grokipedia-api
Project-URL: Issues, https://github.com/AkeBoss-tech/grokipedia-api/issues
Keywords: grokipedia,wiki,knowledge,api,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Grokipedia API

A Python client for accessing content from [Grokipedia](https://grokipedia.com/), 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

## Installation

Install from PyPI (when available):

```bash
pip install grokipedia-api
```

Or install from source:

```bash
git clone https://github.com/yourusername/grokipedia-api.git
cd grokipedia-api
pip install -e .
```

## Quick Start

### Basic Usage

```python
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

```python
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

```python
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']}")
```

### Using Context Manager

```python
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'])
```

## 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:**
```python
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:**
```python
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:**
```python
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

```python
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

```bash
# Clone the repository
git clone https://github.com/yourusername/grokipedia-api.git
cd grokipedia-api

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

### Running Tests

```bash
# Run all tests
pytest

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

### Code Style

This project uses:
- [Black](https://black.readthedocs.io/) for code formatting
- [Ruff](https://ruff.rs/) for linting
- [mypy](https://mypy.readthedocs.io/) for type checking

```bash
# 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](https://grokipedia.com/) 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](https://github.com/yourusername/grokipedia-api/issues).

## Changelog

### 0.1.0 (2025-01-09)

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

