alephantai-analytics-api 0.1.0__tar.gz

alephantai_analytics_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-08
+
+### Added
+- Initial release of Alephant Analytics API Python client
+- Support for Analytics Atomic endpoints (health, ping)  
+- Support for Analytics SaaS endpoints (request logs, usage analytics)
+- Async and sync client implementations
+- JWT and API key authentication
+- Comprehensive error handling
+- Type hints and Pydantic models
+- Development tools configuration (black, isort, mypy)
+
+### Features
+- Generated from Fern API definition for consistency
+- Full type safety with mypy
+- Async/await support
+- Configurable timeouts and retries
+- Environment variable configuration
+- Detailed documentation and examples
+
+### Dependencies
+- httpx >= 0.25.0
+- pydantic >= 2.0.0
+- typing-extensions >= 4.0.0

alephantai_analytics_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alephant AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alephantai_analytics_api-0.1.0/MANIFEST.in

@@ -0,0 +1,36 @@
+# Package directory mapping: pyproject.toml declares `alephant_logs_collector = "."`
+# This means the entire current directory is mapped to the package name `alephant_logs_collector`
+# We include specific directories and files to avoid build artifacts
+
+include README.md
+include CHANGELOG.md
+include LICENSE
+include pyproject.toml
+
+# Include root-level Python files
+include __init__.py
+include client.py
+include environment.py
+
+# Include package directories explicitly
+recursive-include core *.py
+recursive-include core *.typed
+recursive-include commons *.py
+recursive-include commons *.typed
+recursive-include analytics_atomic *.py
+recursive-include analytics_atomic *.typed
+recursive-include analytics_saas *.py
+recursive-include analytics_saas *.typed
+
+# Exclude test files and development artifacts
+prune tests
+exclude test_package.py
+
+# Global excludes
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store
+global-exclude *.egg-info
+global-exclude build
+global-exclude dist
+global-exclude test_package.py

alephantai_analytics_api-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+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.

alephantai_analytics_api-0.1.0/README.md

@@ -0,0 +1,267 @@
+# 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.