Metadata-Version: 2.4
Name: alephantai-analytics-api
Version: 0.1.0
Summary: Python client for Alephant Analytics API
Author-email: Alephant AI <support@alephant.io>
License-Expression: MIT
Project-URL: Homepage, https://github.com/alephant-ai/alephantai-analytics-api
Project-URL: Documentation, https://docs.alephant.io/analytics-api
Project-URL: Repository, https://github.com/alephant-ai/alephantai-analytics-api
Project-URL: Issues, https://github.com/alephant-ai/alephantai-analytics-api/issues
Keywords: alephant,analytics,api,client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# Alephant Analytics API Python Client

Official Python client for the Alephant Analytics API.

## Installation

```bash
pip install alephantai-analytics-api
```

## Package Import

After installation, import the client using the Python package name:

```python
# PyPI package name: alephantai-analytics-api  
# Python import name: alephant_logs_collector
from alephant_logs_collector import LogsCollectorAnalyticsClient
```

**Note**: The PyPI package name (`alephantai-analytics-api`) differs from the Python import name (`alephant_logs_collector`) due to Fern generator naming conventions.

## Quick Start

```python
import os

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

# Manually read environment variables and configure client
api_key = os.environ.get("ALEPHANT_API_KEY")
client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
)

# Public health probe (auth optional)
health = client.analytics_atomic.get_health()
print(f"Service status: {health.data.status}")
```

## Configuration

### Environment Variables

The SDK does not automatically read environment variables. You must manually read them in your code and pass them to the client constructor.

**Recommended environment variables**:

| Variable | Description |
|----------|-------------|
| `ALEPHANT_API_KEY` | Your API key, virtual key, or PAT — passed as Bearer token via `headers` parameter |
| `ALEPHANT_BASE_URL` | Base URL for the API (e.g. `https://analytics.alephant.io`) — passed via `base_url` parameter |

**Example with manual environment variable reading**:

```python
import os

from alephant_logs_collector import LogsCollectorAnalyticsClient

# Manually read environment variables
base_url = os.environ.get("ALEPHANT_BASE_URL")
api_key = os.environ.get("ALEPHANT_API_KEY")

client = LogsCollectorAnalyticsClient(
    base_url=base_url,
    headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
)
```

### Client Options

```python
from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    base_url="https://analytics.alephant.io",  # optional; overrides environment URL when set
    timeout=30.0,  # seconds; default 60 when using the default httpx client
    follow_redirects=True,
    headers=None,  # default headers for every request (e.g. Authorization, Cookie)
)
```

## Authentication

The API accepts **Bearer JWT**, **virtual key**, or **PAT** on the `Authorization` header. The Python client does not expose a dedicated `api_key` constructor argument; wire credentials using one of the patterns below.

### API Key (Bearer token)

Pass the token on each call, or set default headers on the client.

```python
import os

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

token = os.environ["ALEPHANT_API_KEY"]

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": f"Bearer {token}"},
)

# Or per-request (overrides / supplements per method signature)
client.analytics_atomic.get_live24h_summary(
    authorization=f"Bearer {token}",
    x_workspace_id="00000000-0000-0000-0000-000000000000",
)
```

### JWT Token

Use the same `Authorization: Bearer <jwt>` form — either via `headers=` on the client or the `authorization=` parameter on endpoints.

```python
client = LogsCollectorAnalyticsClient(
    base_url="https://analytics.alephant.io",
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},
)
```

### Cookie Auth

The server also accepts the `alephant_token` cookie. Model it with default headers (or a custom `httpx` client):

```python
import httpx
from alephant_logs_collector import LogsCollectorAnalyticsClient

cookie_client = httpx.Client(timeout=30.0)
client = LogsCollectorAnalyticsClient(
    base_url="https://analytics.alephant.io",
    httpx_client=cookie_client,
    headers={"Cookie": "alephant_token=YOUR_SESSION_TOKEN"},
)
```

Authenticated routes typically require `x_workspace_id` (`X-Workspace-Id`) as well — pass `x_workspace_id="..."` on each method that supports it.

## API Reference

For full request/response shapes, see `reference.md` in this package.

### Analytics Atomic

| Method | Description |
|--------|-------------|
| `client.analytics_atomic.get_health()` | Public health probe (`GET` health). |
| `client.analytics_atomic.post_aggregate_ping()` | Connectivity check against aggregate tables. |
| `client.analytics_atomic.post_detail_ping()` | Connectivity check against detail/RMT paths. |
| `client.analytics_atomic.get_live24h_summary()` | Rolling ~24h workspace totals. |
| `client.analytics_atomic.get_usage_summary()` | Daily KPIs for a window vs previous period. |
| `client.analytics_atomic.get_usage_timeseries()` | Time series for cost/requests/tokens/etc. |
| `client.analytics_atomic.get_request_logs(start=..., end=...)` | Request log list for a time window. |
| `client.analytics_atomic.get_request_log_by_id(request_id=...)` | Single request log by ID. |
| `client.analytics_atomic.get_by_department()` / `get_by_agent()` / `get_by_member()` | Cost/usage breakdown helpers. |
| `client.analytics_atomic.get_master_keys_*()` | Master key vault, spend, and breakdown endpoints. |

### Analytics SaaS

| Method | Description |
|--------|-------------|
| `client.analytics_saas.get_saas_overview()` | SaaS dashboard overview. |
| `client.analytics_saas.get_saas_live24h()` | Live-24h style panel (top models/keys, etc.). |
| `client.analytics_saas.get_saas_usage(date_from=..., date_to=...)` | Daily usage series for the workspace. |
| `client.analytics_saas.get_saas_logs(...)` | SaaS request logs listing (filters per API). |
| `client.analytics_saas.get_saas_logs_stats()` | Log statistics for the SaaS UI. |
| `client.analytics_saas.get_saas_costs()` / `get_saas_models()` / `get_saas_sparklines()` | Costs, models, sparklines. |
| `client.analytics_saas.get_saas_agent_analytics()` / `get_saas_member_analytics()` | Agent/member analytics. |

## Error Handling

Non-2xx responses and some parse failures raise `ApiError` from `alephant_logs_collector.core`.

```python
from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.core import ApiError
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": "Bearer your-token"},
)

try:
    data = client.analytics_atomic.get_request_logs(
        start="2025-01-01T00:00:00Z",
        end="2025-01-02T00:00:00Z",
        x_workspace_id="your-workspace-uuid",
    )
    print(data)
except ApiError as e:
    # e.status_code: HTTP status; e.body: parsed JSON or raw text; e.headers: response headers
    print(f"API error: status={e.status_code}, body={e.body}")
```

## Async Support

Use `AsyncLogsCollectorAnalyticsClient` with `async`/`await`. Method names mirror the sync client.

```python
import asyncio
import os

from alephant_logs_collector import AsyncLogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment


async def main() -> None:
    # Manually read environment variables
    api_key = os.environ.get("ALEPHANT_API_KEY")
    client = AsyncLogsCollectorAnalyticsClient(
        environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
        headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
    )
    health = await client.analytics_atomic.get_health()
    print(health.data.status)


asyncio.run(main())
```

## Development

From the directory that contains `pyproject.toml` (this SDK root):

### Installing Dev Dependencies

```bash
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black .
isort .
```

### Type Checking

```bash
mypy .
```

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

## Support

For support, contact [support@alephant.io](mailto:support@alephant.io) or open an issue on GitHub.

## Documentation

See [Alephant Analytics API documentation](https://docs.alephant.io/analytics-api) and the generated `reference.md` in this repository for endpoint-level detail.
