docs | LAY-881 Initial version of the SDK docs for gitbooks

.github/workflows/sync-docs.yaml

@@ -0,0 +1,19 @@
+name: Sync Docs to GitBook
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**"]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      steps:
+        - uses: actions/checkout@v3
+        - name: GitBook Sync
+          uses: gitbook/gitbook-sync@v1
+          with:
+            gitbook-token: ${{ secrets.GITBOOK_TOKEN }}
+            gitbook-space: ${{ secrets.GITBOOK_SPACE_ID }}
+            source-dir: docs/

docs/README.md

@@ -0,0 +1,59 @@
+# Atlas Python SDK Documentation
+
+Welcome to the official documentation for the Atlas Python SDK. This library provides convenient access to the LayerLens Atlas REST API from any Python 3.8+ application.
+
+## What is Atlas?
+
+Atlas is LayerLens's evaluation platform that allows you to benchmark AI models against various datasets and metrics. The Python SDK provides a synchronous HTTP client powered by [httpx](https://github.com/encode/httpx) and [Pydantic](https://pydantic.dev/) models for type-safe API interactions.
+
+## Key Features
+
+- **Simple Authentication**: Secure API key-based authentication
+- **Type Safety**: Full Pydantic model support for all API responses
+- **Comprehensive Error Handling**: Detailed exception hierarchy for different error scenarios
+- **Configurable Timeouts**: Fine-grained timeout control for different operations
+- **Environment Variable Support**: Easy configuration through environment variables
+- **Python 3.8+ Compatibility**: Works with modern Python versions
+
+## Quick Start
+
+```python
+import os
+from atlas import Atlas
+
+# Initialize the client
+client = Atlas(
+    api_key=os.environ.get("LAYERLENS_ATLAS_API_KEY"),
+    organization_id=os.environ.get("LAYERLENS_ATLAS_ORG_ID"), 
+    project_id=os.environ.get("LAYERLENS_ATLAS_PROJECT_ID"),
+)
+
+# Create an evaluation
+evaluation = client.evaluations.create(
+    model="gpt-4",
+    benchmark="mmlu"
+)
+
+# Get results
+if evaluation:
+    results = client.results.get(evaluation_id=evaluation.id)
+    print(f"Evaluation completed with {len(results)} results")
+```
+
+## Navigation
+
+- **[Getting Started](getting-started/)** - Installation, setup, and your first API call
+- **[API Reference](api-reference/)** - Complete documentation of all available methods
+- **[Code Examples](examples/)** - Practical examples for common use cases
+- **[Troubleshooting](troubleshooting/)** - Solutions to common issues
+- **[Security](security/)** - Best practices for secure API usage
+
+## Support
+
+- **LayerLens Support**: Contact support through your LayerLens dashboard
+- **Documentation**: Visit [docs.layerlens.com](https://docs.layerlens.com) for additional resources
+- **API Status**: Check the [LayerLens status page](https://status.layerlens.com) for service updates
+
+## License
+
+This SDK is released under the MIT License.

docs/SUMMARY.md

@@ -0,0 +1,33 @@
+# Table of Contents
+
+* [Introduction](README.md)
+
+## Getting Started
+* [Installation](getting-started/installation.md)
+* [Authentication & Configuration](getting-started/authentication.md)
+* [Quick Start Guide](getting-started/quickstart.md)
+
+## API Reference
+* [Client Configuration](api-reference/client.md)
+* [Evaluations](api-reference/evaluations.md)
+* [Results](api-reference/results.md)
+* [Models & Benchmarks](api-reference/models-benchmarks.md)
+* [Error Handling](api-reference/errors.md)
+
+## Code Examples
+* [Creating Evaluations](examples/creating-evaluations.md)
+* [Retrieving Results](examples/retrieving-results.md)
+* [Working with Timeouts](examples/timeouts.md)
+* [Advanced Usage Patterns](examples/advanced-usage.md)
+
+## Troubleshooting
+* [Common Issues](troubleshooting/common-issues.md)
+* [Authentication Problems](troubleshooting/authentication.md)
+* [Error Codes Reference](troubleshooting/error-codes.md)
+
+## Security Best Practices
+* [API Key Management](security/api-key-management.md)
+* [Environment Variables](security/environment-variables.md)
+* [Rate Limiting](security/rate-limiting.md)
+* [Data Privacy](security/data-privacy.md)
+

docs/api-reference/client.md

@@ -0,0 +1,277 @@
+# Client Configuration
+
+The `Atlas` class is the main entry point for interacting with the LayerLens Atlas API. This page covers client initialization, configuration options, and advanced usage patterns.
+
+## Basic Usage
+
+```python
+from atlas import Atlas
+
+# Using environment variables (recommended)
+client = Atlas()
+
+# Explicit configuration
+client = Atlas(
+    api_key="your_api_key",
+    organization_id="your_org_id",
+    project_id="your_project_id"
+)
+```
+
+## Constructor Parameters
+
+### `Atlas(api_key, organization_id, project_id, base_url, timeout)`
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `api_key` | `str \| None` | Yes* | `None` | Your LayerLens Atlas API key |
+| `organization_id` | `str \| None` | Yes* | `None` | Your organization identifier |
+| `project_id` | `str \| None` | Yes* | `None` | The project you want to work with |
+| `base_url` | `str \| httpx.URL \| None` | No | Atlas API URL | Custom API base URL |
+| `timeout` | `float \| httpx.Timeout \| None` | No | 10 minutes | Request timeout configuration |
+
+*Required unless set via environment variables
+
+## Environment Variable Configuration
+
+The client automatically loads configuration from these environment variables:
+
+```bash
+LAYERLENS_ATLAS_API_KEY="your_api_key_here"
+LAYERLENS_ATLAS_ORG_ID="your_org_id_here"
+LAYERLENS_ATLAS_PROJECT_ID="your_project_id_here"
+LAYERLENS_ATLAS_BASE_URL="https://custom-endpoint.com/api/v1"  # Optional
+```
+
+## Timeout Configuration
+
+### Simple Timeout
+
+```python
+from atlas import Atlas
+
+# 30-second timeout for all requests
+client = Atlas(timeout=30.0)
+```
+
+### Advanced Timeout Configuration
+
+```python
+import httpx
+from atlas import Atlas
+
+client = Atlas(
+    timeout=httpx.Timeout(
+        connect=5.0,    # Connection timeout: 5 seconds
+        read=60.0,      # Read timeout: 60 seconds  
+        write=30.0,     # Write timeout: 30 seconds
+        pool=10.0       # Connection pool timeout: 10 seconds
+    )
+)
+```
+
+### Per-Request Timeout Override
+
+```python
+client = Atlas()
+
+# Override timeout for a specific request
+evaluation = client.with_options(timeout=120.0).evaluations.create(
+    model="gpt-4",
+    benchmark="mmlu"
+)
+```
+
+## Client Methods
+
+### `copy(**kwargs)`
+
+Create a new client instance with modified configuration:
+
+```python
+# Base client
+client = Atlas(api_key="key1", organization_id="org1")
+
+# Create a copy with different project
+project_client = client.copy(project_id="different_project")
+
+# Create a copy with different timeout
+slow_client = client.copy(timeout=300.0)  # 5 minutes
+```
+
+### `with_options(**kwargs)`
+
+Temporarily override client options for a single request chain:
+
+```python
+client = Atlas()
+
+# Use different timeout for this request only
+evaluation = client.with_options(timeout=60.0).evaluations.create(
+    model="gpt-4", 
+    benchmark="mmlu"
+)
+
+# Back to original timeout for subsequent requests
+results = client.results.get(evaluation_id=evaluation.id)
+```
+
+## Resource Access
+
+The client provides access to different API resources through properties:
+
+```python
+client = Atlas()
+
+# Access evaluations resource
+client.evaluations.create(model="gpt-4", benchmark="mmlu")
+
+# Access results resource  
+client.results.get(evaluation_id="eval_123")
+```
+
+Available resources:
+- `client.evaluations` - Create and manage evaluations
+- `client.results` - Retrieve evaluation results
+- More resources coming soon...
+
+## Error Handling
+
+The client raises specific exceptions for different error conditions:
+
+```python
+import atlas
+from atlas import Atlas
+
+client = Atlas()
+
+try:
+    evaluation = client.evaluations.create(model="invalid", benchmark="invalid")
+except atlas.AuthenticationError:
+    # 401 - Invalid API key
+    print("Authentication failed")
+except atlas.PermissionDeniedError:
+    # 403 - Valid API key, insufficient permissions  
+    print("Permission denied")
+except atlas.NotFoundError:
+    # 404 - Resource not found
+    print("Model or benchmark not found")
+except atlas.RateLimitError:
+    # 429 - Too many requests
+    print("Rate limit exceeded")
+except atlas.InternalServerError:
+    # 500+ - Server error
+    print("Server error occurred")
+except atlas.APIConnectionError:
+    # Network/connection issues
+    print("Connection failed")
+except atlas.APITimeoutError:
+    # Request timeout
+    print("Request timed out")
+```
+
+## Authentication Headers
+
+The client automatically handles authentication by adding the required headers:
+
+```python
+# The client adds this header to all requests:
+# x-api-key: your_api_key_value
+```
+
+You don't need to manually handle authentication headers.
+
+## Base URL Configuration
+
+### Default Base URL
+The client uses the default LayerLens Atlas API endpoint unless overridden.
+
+### Custom Base URL
+For enterprise or self-hosted deployments:
+
+```python
+from atlas import Atlas
+
+client = Atlas(
+    base_url="https://your-atlas-instance.com/api/v1"
+)
+
+# Or via environment variable
+# LAYERLENS_ATLAS_BASE_URL="https://your-atlas-instance.com/api/v1"
+client = Atlas()  # Will use custom base URL from environment
+```
+
+## Best Practices
+
+### 1. Use Environment Variables
+```python
+# ✅ Good - secure and flexible
+client = Atlas()
+
+# ❌ Bad - hardcoded credentials
+client = Atlas(api_key="hardcoded_key")
+```
+
+### 2. Configure Appropriate Timeouts
+```python
+# ✅ Good - reasonable timeout for evaluation creation
+client = Atlas(timeout=120.0)  # 2 minutes
+
+# ❌ Bad - too short for long-running operations
+client = Atlas(timeout=5.0)  # 5 seconds might be too short
+```
+
+### 3. Handle Errors Gracefully
+```python
+# ✅ Good - specific error handling
+try:
+    evaluation = client.evaluations.create(model="gpt-4", benchmark="mmlu")
+except atlas.RateLimitError:
+    time.sleep(60)  # Wait before retrying
+    evaluation = client.evaluations.create(model="gpt-4", benchmark="mmlu")
+except atlas.APIError as e:
+    logger.error(f"API error: {e}")
+    raise
+```
+
+### 4. Reuse Client Instances
+```python
+# ✅ Good - reuse the same client
+client = Atlas()
+eval1 = client.evaluations.create(model="gpt-4", benchmark="mmlu")
+eval2 = client.evaluations.create(model="claude-3", benchmark="hellaswag")
+
+# ❌ Bad - creating new clients unnecessarily
+client1 = Atlas()
+eval1 = client1.evaluations.create(model="gpt-4", benchmark="mmlu")
+client2 = Atlas()  # Unnecessary
+eval2 = client2.evaluations.create(model="claude-3", benchmark="hellaswag")
+```
+
+## Thread Safety
+
+The Atlas client is thread-safe and can be shared across multiple threads:
+
+```python
+import threading
+from atlas import Atlas
+
+client = Atlas()
+
+def create_evaluation(model_name):
+    evaluation = client.evaluations.create(
+        model=model_name,
+        benchmark="mmlu"
+    )
+    print(f"Created evaluation for {model_name}: {evaluation.id}")
+
+# Safe to use the same client across threads
+threads = []
+for model in ["gpt-4", "claude-3", "llama-2"]:
+    thread = threading.Thread(target=create_evaluation, args=(model,))
+    threads.append(thread)
+    thread.start()
+
+for thread in threads:
+    thread.join()
+```