Metadata-Version: 2.4
Name: aegis-research
Version: 0.1.0
Summary: Python SDK for Aegis Research API - AI-powered web research as a service
Project-URL: Homepage, https://aegis.rbnk.uk/research
Project-URL: Documentation, https://aegis.rbnk.uk/api-docs
Project-URL: Repository, https://github.com/aegis-agent/aegis-research-sdk
Project-URL: Changelog, https://github.com/aegis-agent/aegis-research-sdk/blob/main/CHANGELOG.md
Author-email: Aegis <aegis@richardbankole.com>
License-Expression: MIT
License-File: LICENSE
Keywords: aegis,ai,api,llm,research,web-research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Aegis Research SDK

Python SDK for the [Aegis Research API](https://aegis.rbnk.uk/research) - AI-powered web research as a service.

## Installation

```bash
pip install aegis-research
```

## Quick Start

```python
from aegis_research import AegisResearch

# Initialize client
client = AegisResearch(api_key="res_your_api_key")

# Execute research
result = client.research("Best practices for API rate limiting in 2025")

print(result.summary)
for finding in result.key_findings:
    print(f"- {finding}")
```

## Features

- **AI-Powered Research**: Get synthesized research results, not just search links
- **Multiple Depth Levels**: Choose shallow (1 credit), medium (3 credits), or deep (10 credits) research
- **Caching**: Results cached for 24 hours to save credits
- **Source Citations**: Every claim backed by sources

## Usage

### Research

```python
# Basic research
result = client.research("What is quantum computing?")

# Deep research with more sources
result = client.research(
    "Impact of AI on healthcare in 2025",
    depth="deep",  # 10 credits, 10+ sources
    use_cache=False  # Force fresh research
)

# Include specific URLs
result = client.research(
    "Compare FastAPI vs Flask",
    urls=["https://fastapi.tiangolo.com", "https://flask.palletsprojects.com"]
)
```

### Check Credits

```python
status = client.credits()
print(f"Credits remaining: {status.credits_remaining}")
print(f"Tier: {status.tier}")
```

### Research History

```python
history = client.history(limit=10)
for item in history:
    print(f"{item['id']}: {item['topic']}")
```

### Get Previous Result

```python
result = client.get_research("res_abc123")
```

## Response Format

```python
ResearchResult:
    id: str                     # "res_abc123"
    topic: str                  # Original query
    status: str                 # "completed", "cached", "failed"
    summary: str                # Executive summary (2-3 sentences)
    key_findings: List[str]     # Main findings as bullet points
    detailed_analysis: str      # Full analysis
    sources: List[Source]       # Cited sources
    source_count: int           # Number of sources
    depth: str                  # "shallow", "medium", "deep"
    cached: bool                # Whether result was cached
    credits_used: int           # Credits consumed
    duration_ms: int            # Time taken
```

## Depth Levels

| Depth | Credits | Sources | Time | Use Case |
|-------|---------|---------|------|----------|
| shallow | 1 | 3 | ~2 min | Quick facts, verification |
| medium | 3 | 5-7 | ~5 min | General research, decisions |
| deep | 10 | 10+ | ~15 min | Comprehensive investigation |

## Error Handling

```python
from aegis_research import (
    AegisError,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
)

try:
    result = client.research("topic")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited: {e}")
except InsufficientCreditsError:
    print("Not enough credits")
except AegisError as e:
    print(f"API error: {e}")
```

## Pricing

| Tier | Price | Credits/Month | Rate Limit |
|------|-------|---------------|------------|
| Free | $0 | 50 | 5/min |
| Starter | $9/mo | 500 | 20/min |
| Pro | $49/mo | 5,000 | 60/min |

Get your API key at [aegis.rbnk.uk/research](https://aegis.rbnk.uk/research)

## License

MIT
