### Installing SmartSurge with pip

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates the basic installation of the SmartSurge library using pip, the Python package installer. It installs the core library without any optional dependencies.

```bash
pip install smartsurge
```

--------------------------------

### Installing SmartSurge with Optional Extras

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how to install SmartSurge along with various optional extras, such as development tools, benchmarking tools, or documentation tools. Users can select specific extras or install all of them for extended functionality.

```bash
# Install with development tools (testing, linting, etc.)
pip install smartsurge[dev]

# Install with benchmarking tools
pip install smartsurge[benchmark]

# Install with documentation tools
pip install smartsurge[docs]

# Install all extras
pip install smartsurge[dev,benchmark,docs]
```

--------------------------------

### Verifying SmartSurge Benchmark Installation - Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet checks if the optional benchmark components for the `smartsurge` library are installed. It uses `smartsurge.has_benchmarks()` to determine availability and provides installation instructions if they are missing.

```python
import smartsurge
if smartsurge.has_benchmarks():
    print("Benchmarks available!")
else:
    print("Install with: pip install smartsurge[benchmark]")
```

--------------------------------

### Making a Basic GET Request with SmartSurge

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet illustrates how to create a SmartSurge client and perform a simple GET request to an external API. It demonstrates accessing the response status code and parsing the JSON content, similar to the `requests` library.

```python
from smartsurge import SmartSurgeClient

# Create a client - it works just like requests!
client = SmartSurgeClient()

# Make a simple GET request
response = client.get("https://api.github.com/users/github")

# Use the response exactly like requests
print(response.status_code)
print(response.json())
```

--------------------------------

### Checking SmartSurge Version - Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet imports the `smartsurge` library and prints its installed version number. It's used to verify the current SmartSurge library version.

```python
import smartsurge
print(smartsurge.__version__)
```

--------------------------------

### Reusing SmartSurge Client Configurations

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates how to use `ClientConfig` to define reusable configurations for SmartSurge clients. This allows for creating multiple client instances with identical settings, promoting consistency and reducing redundancy.

```python
from smartsurge import SmartSurgeClient, ClientConfig

# Create configuration
config = ClientConfig(
    base_url="https://api.example.com",
    timeout=(10.0, 30.0),
    max_retries=3,
    user_agent="MyApp/1.0 (SmartSurge)"
)

# Create multiple clients with same config
client1 = SmartSurgeClient(**config.model_dump())
client2 = SmartSurgeClient(**config.model_dump())
```

--------------------------------

### Performing a Simple GET Request with SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

Demonstrates how to create a SmartSurgeClient and make a basic GET request to an API endpoint. It also shows how to retrieve the request history, providing insights into redirects or retries.

```python
from smartsurge import SmartSurgeClient  # or Client (alias)

# Create a client
client = SmartSurgeClient()

# Make a GET request
response = client.get("https://api.example.com/data")

# Print the response
print(f"Status code: {response.status_code}")
print(f"Response data: {response.json()}")

# Get request with history
response, history = client.get("https://api.example.com/data", return_history=True)
print(f"Request history contains {len(history.requests)} requests")
```

--------------------------------

### Complete SmartSurge Client Usage Example in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This comprehensive example demonstrates a full workflow using the SmartSurge client, including logging configuration, custom client initialization, setting rate limits, making authenticated and unauthenticated GET requests, handling rate limit responses, and streaming file downloads. It also shows proper client cleanup.

```Python
from smartsurge import Client, RateLimitExceeded
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)

# Create client with configuration
client = Client(
    base_url="https://api.github.com",
    max_retries=5,
    refit_every=20
)

try:
    # Set known rate limit
    client.set_rate_limit(
        endpoint="/users",
        method="GET",
        max_requests=60,
        time_period=3600  # GitHub's unauthenticated rate limit
    )
    
    # Make requests
    for username in ["torvalds", "gvanrossum", "dhh"]:
        response, history = client.get(
            f"/users/{username}",
            return_history=True
        )
        
        user = response.json()
        print(f"{user['name']} - {user['public_repos']} repos")
        
        # Check rate limit status
        if history.rate_limit:
            remaining = history.rate_limit.max_requests - len(history)
            print(f"  Rate limit remaining: {remaining}")
    
    # Download a file
    client.stream(
        "https://api.github.com/repos/python/cpython/zipball/master",
        "cpython-master.zip"
    )
    
except RateLimitExceeded as e:
    print(f"Rate limit exceeded: {e.message}")
    if e.retry_after:
        print(f"Retry after {e.retry_after} seconds")
        
finally:
    client.close()
```

--------------------------------

### Installing SmartSurge Python Library

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This snippet demonstrates how to install the SmartSurge library using pip, the Python package installer. It's the first step to integrating SmartSurge into your Python projects.

```bash
pip install smartsurge
```

--------------------------------

### Integrating SmartSurge Benchmarks with Pyperf (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/benchmarks/BENCHMARKS.md

This snippet demonstrates how to use `pyperf` for statistically rigorous benchmarking of SmartSurge. It covers installing `pyperf`, running a benchmark with specific warmups and values, comparing results from different runs, and generating statistics from a results file.

```bash
# Install pyperf first
pip install pyperf

# Run with pyperf
python -m pyperf run \
    --warmups 1 \
    --values 3 \
    -o results.json \
    -m smartsurge.benchmarks.benchmark_hmm_effectiveness \
    -- --mode demo

# Compare results
python -m pyperf compare_to baseline.json improved.json --table

# Get statistics
python -m pyperf stats results.json
```

--------------------------------

### Performing Asynchronous Requests with SmartSurge

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates SmartSurge's full support for asynchronous operations using `asyncio`. It shows how to create an async client, initiate multiple concurrent `async_get` requests, and await their completion to process responses efficiently.

```python
import asyncio
from smartsurge import SmartSurgeClient

async def fetch_data():
    client = SmartSurgeClient()
    
    # Make async requests
    tasks = []
    for i in range(10):
        task = client.async_get(f"https://api.example.com/data/{i}")
        tasks.append(task)
    
    # Wait for all requests
    responses = await asyncio.gather(*tasks)
    
    # Process responses
    for response in responses:
        data = await response.json()
        print(f"Status: {response.status}")

# Run the async function
asyncio.run(fetch_data())
```

--------------------------------

### Basic SmartSurge Client Configuration

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates how to configure fundamental SmartSurge client settings during initialization. It covers setting a global request timeout and the maximum number of retry attempts for failed requests.

```python
from smartsurge import SmartSurgeClient

client = SmartSurgeClient(
    timeout=30.0,              # Request timeout in seconds
    max_retries=5              # Maximum retry attempts
)
```

--------------------------------

### Example: Getting Rate Limit Details (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This example shows how to use `get_rate_limit` to fetch and display the rate limit details for the `/api/users` GET endpoint. If a limit is found, it prints the `max_requests`, `time_period`, and `source` of the rate limit, providing insight into its configuration.

```python
limit = client.get_rate_limit("/api/users", "GET")
if limit:
    print(f"Rate limit: {limit.max_requests} per {limit.time_period}s")
    print(f"Source: {limit.source}")
```

--------------------------------

### Advanced SmartSurge Client Configuration

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet showcases a comprehensive set of advanced configuration options for the SmartSurge client. It includes settings for base URL, detailed timeouts, retry logic (backoff factor), rate limit detection parameters, HMM settings, and SSL verification.

```python
from smartsurge import SmartSurgeClient

client = SmartSurgeClient(
    # Base URL for all requests
    base_url="https://api.example.com",
    
    # Timeout settings
    timeout=(5.0, 30.0),       # (connect, read) timeouts
    
    # Retry settings
    max_retries=10,
    backoff_factor=0.3,        # Exponential backoff multiplier
    
    # Rate limit detection
    min_time_period=1.0,       # Minimum rate limit window (seconds)
    max_time_period=3600.0,    # Maximum rate limit window (seconds)
    
    # HMM settings
    refit_every=20,            # Refit HMM after N responses
    
    # SSL and verification
    verify_ssl=True
)
```

--------------------------------

### Installing SmartSurge with pip in Bash

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/index.md

This section provides commands for installing the SmartSurge library using `pip`. It covers basic installation and options for installing additional dependencies for development, benchmarking, or documentation purposes, allowing users to set up their environment based on their specific needs.

```bash
pip install smartsurge
```

```bash
# Install with development tools
pip install smartsurge[dev]

# Install with benchmarking support
pip install smartsurge[benchmark]

# Install with documentation tools
pip install smartsurge[docs]

# Install everything
pip install smartsurge[dev,benchmark,docs]
```

--------------------------------

### Setting Headers and Authentication in SmartSurge Requests

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet illustrates how to include custom HTTP headers and basic authentication credentials in SmartSurge requests. It shows examples for passing an Authorization token and a User-Agent header, as well as using a username and password for basic authentication.

```python
# Pass headers in requests
response = client.get(
    "https://api.example.com/data",
    headers={
        "Authorization": "Bearer your-token",
        "User-Agent": "MyApp/1.0"
    }
)

# Use basic auth
response = client.get(
    "https://api.example.com/data",
    auth=("username", "password")
)
```

--------------------------------

### API Key Authentication with SmartSurge in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

Illustrates two common methods for API key authentication: passing the key in the request header ('X-API-Key') and as a query parameter ('api_key'). Both examples use the SmartSurgeClient to make a GET request to an example API endpoint.

```python
# In header
client = SmartSurgeClient()
response = client.get(
    "https://api.example.com/data",
    headers={"X-API-Key": "your-api-key"}
)

# In query parameter
response = client.get(
    "https://api.example.com/data",
    params={"api_key": "your-api-key"}
)
```

--------------------------------

### Initializing SmartSurge Client - Basic

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This code shows the most straightforward way to create a SmartSurge client instance. It behaves similarly to the `requests` library, allowing immediate HTTP requests to any specified URL.

```python
from smartsurge import SmartSurgeClient

# Create a client - it works just like requests!
client = SmartSurgeClient()

# Make requests to any URL
response = client.get("https://api.github.com/users/github")
print(response.json())
```

--------------------------------

### Configuring SmartSurge Client - Advanced Options

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This example demonstrates how to configure a SmartSurge client with various options, including `base_url`, `timeout` settings (connect and read), `max_retries` for failed requests, and `verify_ssl` for SSL certificate verification, providing fine-grained control over client behavior.

```python
# Configure client behavior
client = SmartSurgeClient(
    base_url="https://api.example.com",
    timeout=(10.0, 30.0),        # (connect, read) timeouts
    max_retries=5,               # Retry failed requests
    verify_ssl=True              # SSL certificate verification
)
```

--------------------------------

### Configuring SmartSurgeClient with Custom Settings (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

Illustrates how to initialize SmartSurgeClient with custom parameters such as base_url, timeout, max_retries, backoff_factor, verify_ssl, and n_bootstrap. This allows for consistent request behavior across the client's lifespan.

```python
from smartsurge import SmartSurgeClient

# Create a client with custom configuration
client = SmartSurgeClient(
    base_url="https://api.example.com",
    timeout=(10.0, 30.0),  # (connect, read) timeouts
    max_retries=3,
    backoff_factor=0.3,
    verify_ssl=True,
    n_bootstrap=10  # Bootstrap iterations
)

# Now all requests will use the base URL
response = client.get("/users")  # Goes to https://api.example.com/users
```

--------------------------------

### Making HTTP Requests with Custom Headers and Query Parameters in SmartSurge Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This example demonstrates how to include custom HTTP headers (e.g., Authorization, API Version) and URL query parameters (e.g., q, sort, limit) in a GET request using the `SmartSurgeClient`. It shows how to structure these additional request components for API interaction.

```Python
from smartsurge import SmartSurgeClient

client = SmartSurgeClient()

# Request with headers and query parameters
response = client.get(
    "https://api.example.com/search",
    headers={
        "Authorization": "Bearer your-token",
        "X-API-Version": "2.0"
    },
    params={
        "q": "python",
        "sort": "relevance",
        "limit": 10
    }
)

print(f"Search results: {response.json()}")
```

--------------------------------

### Installing Pyperf - Bash

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/benchmarks/README.md

This command installs the `pyperf` library, a tool for statistically rigorous Python benchmarking, which is required to run advanced performance analyses with SmartSurge.

```bash
pip install pyperf
```

--------------------------------

### Streaming Large Files with SmartSurge

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates how to download large files using SmartSurge's streaming API. By setting `stream=True` in the `get` request, the response content can be processed incrementally, which is efficient for large data transfers.

```python
from smartsurge import SmartSurgeClient, JSONStreamingRequest

client = SmartSurgeClient()

# Basic streaming
response = client.get(
    "https://example.com/large-file.zip",
    stream=True
)
```

--------------------------------

### Installing SmartSurge (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/index.md

This snippet demonstrates how to install the SmartSurge library using pip, including an option to install with benchmark extras for performance testing.

```bash
pip install smartsurge

# With benchmark extras
pip install smartsurge[benchmark]
```

--------------------------------

### Advanced Streaming with Resume Support using SmartSurge in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how to use SmartSurge's 'stream_request' method for advanced streaming, including automatic resume support. It specifies a 'JSONStreamingRequest' class, the endpoint URL, a 'state_file' for saving/resuming progress, and a 'chunk_size' of 1MB for efficient data transfer.

```Python
result = client.stream_request(
    streaming_class=JSONStreamingRequest,
    endpoint="https://example.com/large-data.json",
    state_file="download.state",  # Automatically saves/resumes
    chunk_size=1024 * 1024  # 1MB chunks
)
```

--------------------------------

### Installing SmartSurge with Benchmark Support (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Installs the SmartSurge library along with its optional benchmark dependencies, including `pyperf`, `matplotlib`, `numpy`, `flask`, and `werkzeug`, enabling comprehensive benchmarking features.

```bash
pip install smartsurge[benchmark]
```

--------------------------------

### Building a Command-Line Interface for API Interactions - Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This Python script implements a command-line interface (CLI) using `argparse` and `SmartSurgeClient` to perform GET, POST, and rate limit listing operations against an API. It handles JSON data input/output, configures client settings like base URL and timeout, and includes robust error handling for API exceptions.

```python
#!/usr/bin/env python3
"""
CLI tool using SmartSurge for API interactions
"""

import argparse
import json
import sys
from smartsurge import SmartSurgeClient
from smartsurge.exceptions import SmartSurgeException

def main():
    parser = argparse.ArgumentParser(description="API CLI with SmartSurge")
    parser.add_argument("action", choices=["get", "post", "list-limits"])
    parser.add_argument("endpoint", nargs="?", help="API endpoint")
    parser.add_argument("--data", help="JSON data for POST requests")
    parser.add_argument("--base-url", default="https://api.example.com")
    parser.add_argument("--timeout", type=int, default=30)
    parser.add_argument("--pretty", action="store_true", help="Pretty print JSON")
    
    args = parser.parse_args()
    
    # Configure client
    client = SmartSurgeClient(
        base_url=args.base_url,
        timeout=(10.0, float(args.timeout))
    )
    
    try:
        if args.action == "get":
            if not args.endpoint:
                parser.error("endpoint required for get action")
            
            response = client.get(args.endpoint)
            output = response.json()
            
        elif args.action == "post":
            if not args.endpoint or not args.data:
                parser.error("endpoint and --data required for post action")
            
            data = json.loads(args.data)
            response = client.post(args.endpoint, json=data)
            output = response.json()
            
        elif args.action == "list-limits":
            limits = client.list_rate_limits()
            output = {
                f"{endpoint} {method}": {
                    "max": limit.max_requests if limit else None,
                    "period": limit.time_period if limit else None,
                    "source": limit.source if limit else None
                }
                for (endpoint, method), limit in limits.items()
            }
        
        # Output results
        if args.pretty:
            print(json.dumps(output, indent=2))
        else:
            print(json.dumps(output))
            
    except SmartSurgeException as e:
        print(f"Error: {e.message}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Unexpected error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()
```

--------------------------------

### SmartSurge Convenience Methods Example Usage in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This snippet provides practical examples of using SmartSurge's convenience methods (`get`, `post`, `put`, `delete`) for common HTTP operations, including handling JSON data and retrieving request history for analysis.

```python
# GET request
users = client.get("/users", params={"page": 1})

# POST request with JSON
new_user = client.post(
    "/users",
    json={"name": "Alice", "email": "alice@example.com"}
)

# PUT request with form data
updated = client.put(
    "/users/123",
    data={"name": "Alice Smith"}
)

# DELETE request
client.delete("/users/123")

# With request history
response, history = client.get("/api/data", return_history=True)
```

--------------------------------

### Conditionally Importing SmartSurge Benchmarks in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

This snippet demonstrates how to conditionally import and use SmartSurge benchmark functionalities. It checks for benchmark availability using `smartsurge.has_benchmarks()` and raises a `RuntimeError` if they are not installed, guiding the user to install the `[benchmark]` extra. It then proceeds to import and utilize benchmark server creation and configuration.

```python
import smartsurge

HAS_BENCHMARKS = smartsurge.has_benchmarks()

def run_performance_test():
    if not HAS_BENCHMARKS:
        raise RuntimeError(
            "Benchmarks not available. "
            "Install with: pip install smartsurge[benchmark]"
        )
    
    from smartsurge import create_benchmark_server, get_adaptive_config
    
    config = get_adaptive_config()
    server = create_benchmark_server(config)
    # ... run tests
```

--------------------------------

### Performing Basic Asynchronous HTTP GET Requests with SmartSurge Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This snippet illustrates how to make asynchronous GET requests using `SmartSurgeClient` within an `asyncio` event loop. It demonstrates awaiting responses, accessing response status and JSON data, and optionally retrieving the request history for debugging or analysis.

```Python
import asyncio
from smartsurge import SmartSurgeClient

async def fetch_data():
    client = SmartSurgeClient()
    
    # Make an async GET request
    response = await client.async_get(
        "https://api.example.com/data",
        headers={"Authorization": "Bearer token"}
    )
    
    print(f"Status: {response.status}")
    print(f"Data: {await response.json()}")
    
    # Get with history
    response, history = await client.async_get(
        "https://api.example.com/data",
        return_history=True
    )
    print(f"Made {len(history.requests)} total requests")

# Run the async function
asyncio.run(fetch_data())
```

--------------------------------

### Automatic Rate Limit Handling with SmartSurge

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates SmartSurge's automatic rate limit detection and handling capabilities. It shows how the client can make multiple requests to an endpoint, with SmartSurge intelligently pausing and retrying to comply with API rate limits.

```python
from smartsurge import SmartSurgeClient

client = SmartSurgeClient()

# Make many requests - SmartSurge will handle rate limits automatically
for i in range(100):
    response = client.get("https://api.example.com/data")
    print(f"Request {i+1}: {response.status_code}")
```

--------------------------------

### Checking SmartSurge Benchmark Availability (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Demonstrates how to programmatically check if SmartSurge's benchmark components are installed at runtime. If available, it imports `create_benchmark_server`; otherwise, it advises on installation.

```python
import smartsurge

if smartsurge.has_benchmarks():
    print("Benchmarks are available!")
    from smartsurge import create_benchmark_server
else:
    print("Benchmarks not installed. Install with: pip install smartsurge[benchmark]")
```

--------------------------------

### Installing SmartSurge Benchmark Dependencies (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/benchmarks/README.md

This command installs the necessary dependencies for running SmartSurge benchmarks. It uses the `[benchmark]` extra to include optional packages like `flask`, `werkzeug`, `pyperf`, `matplotlib`, and `numpy` required for full benchmarking functionality.

```bash
pip install smartsurge[benchmark]
```

--------------------------------

### Automatic Rate Limit Learning and Listing in SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how SmartSurge automatically learns rate limits through repeated requests when no manual or server-provided limits are present. After making 50 requests, it retrieves and prints the learned (estimated) rate limits for endpoints, demonstrating the HMM-based detection feature.

```Python
# SmartSurge learns automatically as you make requests
for i in range(50):
    response = client.get("https://api.example.com/data")
    
# Check what was learned
limits = client.list_rate_limits()
for (endpoint, method), limit in limits.items():
    if limit and limit.source == "estimated":
        print(f"Learned: {endpoint} allows {limit.max_requests} requests per {limit.time_period}s")
```

--------------------------------

### Retrieving SmartSurge Rate Limit History

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how to retrieve detailed rate limit information detected by SmartSurge. By setting `return_history=True`, users can access the response and a history object, then query the client for learned rate limits per endpoint and method.

```python
# Get response with history
response, history = client.get("https://api.example.com/data", return_history=True)

# Check for detected rate limits
limits = client.list_rate_limits()
for (endpoint, method), limit in limits.items():
    if limit:
        print(f"{endpoint} {method}: {limit.max_requests}/{limit.time_period}s")
        print(f"  Source: {limit.source}")
```

--------------------------------

### Performing Asynchronous Requests with SmartSurge in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This snippet demonstrates how to make asynchronous API requests using SmartSurgeClient and asyncio. It shows fetching data from an example URL and processing the JSON response.

```Python
import asyncio

async def fetch_async():
    client = SmartSurgeClient()
    
    # Make async requests
    response = await client.async_get("https://api.example.com/data")
    data = await response.json()
    
    return data

# Run async function
data = asyncio.run(fetch_async())
```

--------------------------------

### Enabling Detailed Logging for SmartSurge Client in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how to enable detailed logging for the SmartSurge client using Python's 'logging' module and 'smartsurge.configure_logging'. By setting the logging level to 'DEBUG', developers can observe comprehensive internal operations and debug issues more effectively during development.

```Python
import logging
from smartsurge import SmartSurgeClient, configure_logging

# Configure SmartSurge logging
configure_logging(level=logging.DEBUG)

# Create client
client = SmartSurgeClient()

# Make requests - you'll see detailed logs
response = client.get("https://api.example.com/data")
```

--------------------------------

### Installing SmartSurge with pip

Source: https://github.com/dingo-actual/smartsurge/blob/main/README.md

Provides commands to install the SmartSurge library using pip, including options for development, benchmarking, and documentation tools. These commands allow users to set up SmartSurge with various feature sets.

```bash
pip install smartsurge
```

```bash
pip install smartsurge[dev]
```

```bash
pip install smartsurge[benchmark]
```

```bash
pip install smartsurge[docs]
```

```bash
pip install smartsurge[dev,benchmark,docs]
```

--------------------------------

### Installing SmartSurge Core Package (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Installs the core SmartSurge library without the additional benchmark dependencies, suitable for environments where benchmarking features are not required.

```bash
pip install smartsurge
```

--------------------------------

### Manually Setting Rate Limits for Troubleshooting SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet shows how to manually set a rate limit for an endpoint as a troubleshooting step, overriding automatic detection. It configures a strict limit of 10 GET requests per second for 'https://api.example.com/data', which can help diagnose or enforce specific rate limiting behavior.

```Python
# Or manually set rate limits
client.set_rate_limit(
    endpoint="https://api.example.com/data",
    method="GET",
    max_requests=10,
    time_period=1  # 10 requests per second
)
```

--------------------------------

### Performing a Basic Streaming Download with SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

Explains how to initiate a streaming download using JSONStreamingRequest and client.stream_request(). This is useful for handling large files by processing them in chunks rather than loading the entire content into memory.

```python
from smartsurge import SmartSurgeClient, JSONStreamingRequest

client = SmartSurgeClient()

# Create a streaming request
streaming_request = JSONStreamingRequest(
    url="https://example.com/large-file.json",
    method="GET",
    chunk_size=1024 * 1024  # 1MB chunks
)

# Stream download
result = client.stream_request(
    streaming_class=JSONStreamingRequest,
    endpoint="https://example.com/large-file.json",
    chunk_size=1024 * 1024
)

print(f"Download completed: {result}")
```

--------------------------------

### Making Multiple API Requests and Analyzing History with SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This snippet demonstrates how to make multiple GET requests using a SmartSurgeClient instance, enabling request history tracking. It then analyzes the history for each request, printing metrics like total requests, success rate, average response time, and detecting rate limit patterns. The return_history=True parameter is crucial for collecting historical data.

```python
for i in range(10):
    response, history = client.get(
        f"https://api.example.com/items/{i}",
        return_history=True
    )
    
    # Analyze request patterns
    print(f"Request {i+1}:")
    print(f"  Total requests in history: {len(history.requests)}")
    print(f"  Success rate: {history.success_rate:.2%}")
    print(f"  Average response time: {history.avg_response_time:.3f}s")
    
    # Check for detected patterns
    if history.has_rate_limit_pattern:
        print(f"  Rate limit pattern detected!")
```

--------------------------------

### Performing Basic HTTP Requests (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/index.md

This snippet demonstrates the most basic usage of `SmartSurgeClient` to make a GET request to an example API endpoint and print the JSON response.

```python
from smartsurge import SmartSurgeClient

# Simple requests
client = SmartSurgeClient()
response = client.get("https://api.example.com/data")
print(response.json())
```

--------------------------------

### Checking and Initializing SmartSurge Benchmark Server (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/index.md

This snippet demonstrates how to check for the availability of benchmark support in the smartsurge library. If benchmarks are available, it shows how to create a benchmark server; otherwise, it provides instructions for installing the necessary dependencies.

```python
import smartsurge

if smartsurge.has_benchmarks():
    from smartsurge import create_benchmark_server
    server = create_benchmark_server()
else:
    print("Install with: pip install smartsurge[benchmark]")
```

--------------------------------

### Integrating SmartSurge Client into Flask Application

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This Flask application demonstrates how to integrate the `SmartSurgeClient` for making API requests. It shows client configuration using environment variables, setting up global rate limits, caching API responses with `lru_cache`, and defining various API routes for GET and POST operations, including a route to display current rate limit status.

```python
from flask import Flask, jsonify, request
from smartsurge import SmartSurgeClient
from functools import lru_cache
import os

app = Flask(__name__)

# Configure client with environment variables
client = SmartSurgeClient(
    base_url=os.getenv("API_BASE_URL", "https://api.example.com"),
    timeout=(5.0, 30.0),
    max_retries=3
)

# Set known rate limits
client.set_rate_limit(
    endpoint=client.base_url,
    method="GET",
    max_requests=100,
    time_period=60  # 100 requests per minute
)

# Cache results to reduce API calls
@lru_cache(maxsize=128)
def cached_get(endpoint: str):
    """Cached GET request"""
    response = client.get(endpoint)
    return response.json()

@app.route('/api/users')
def get_users():
    try:
        # Using the configured base_url
        response = client.get("/users")
        return jsonify(response.json())
    except Exception as e:
        return jsonify({"error": str(e)}), 500

@app.route('/api/users/<int:user_id>')
def get_user(user_id):
    try:
        response = client.get(f"/users/{user_id}")
        return jsonify(response.json())
    except Exception as e:
        return jsonify({"error": str(e)}), 500

@app.route('/api/users', methods=['POST'])
def create_user():
    try:
        response = client.post(
            "/users",
            json=request.json
        )
        return jsonify(response.json()), 201
    except Exception as e:
        return jsonify({"error": str(e)}), 500

@app.route('/api/rate-limits')
def show_rate_limits():
    """Show current rate limit status"""
    limits = client.list_rate_limits()
    return jsonify({
        f"{endpoint} {method}": {
            "max": limit.max_requests if limit else None,
            "period": limit.time_period if limit else None,
            "source": limit.source if limit else None
        }
        for (endpoint, method), limit in limits.items()
    })

if __name__ == '__main__':
    app.run(debug=True)
```

--------------------------------

### Best Practice: Reusing SmartSurge Client Instances in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This example illustrates the best practice of reusing a single SmartSurgeClient instance for multiple requests to leverage connection pooling and improve performance. It contrasts with creating a new client for each request, which is inefficient.

```Python
# Good - reuse client (connection pooling)
client = SmartSurgeClient()
for url in urls:
    response = client.get(url)

# Bad - creates new client each time
for url in urls:
    client = SmartSurgeClient()
    response = client.get(url)
```

--------------------------------

### Managing SmartSurgeClient Sessions (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

Explains that SmartSurgeClient automatically handles session management, allowing multiple requests to be made using the same client instance without explicit session handling. This simplifies resource management and improves performance.

```python
from smartsurge import SmartSurgeClient

# SmartSurgeClient automatically handles session management
client = SmartSurgeClient()

# Make multiple requests
response1 = client.get("https://api.example.com/users")
response2 = client.get("https://api.example.com/products")

# Use the responses
print(f"Users: {response1.json()}")
print(f"Products: {response2.json()}")
```

--------------------------------

### SmartSurgeClient Usage Examples in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

Provides various examples of instantiating and using the `SmartSurgeClient`. It covers basic usage, configuring the client with custom parameters like `base_url`, `max_retries`, and `rate_limit`, using the client as a context manager, retrieving request history, and disabling the HMM rate limit detection model.

```python
from smartsurge import Client

# Basic usage
client = Client()
response = client.get("https://api.example.com/users")

# With configuration
client = Client(
    base_url="https://api.example.com",
    max_retries=5,
    rate_limit={'requests': 100, 'period': 60}  # 100 requests per minute
)

# Using context manager
with Client() as client:
    response = client.get("/users")
    # Session automatically closed on exit

# With request history
response, history = client.get("/users", return_history=True)
print(f"Success rate: {history.success_rate():.2%}")
print(f"Total requests: {len(history)}")

# Create client with HMM disabled
client_no_hmm = Client(
    base_url="https://api.example.com",
    model_disabled=True  # No rate limit detection
)
```

--------------------------------

### Setting Manual Rate Limits for All Methods on an Endpoint in SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet illustrates how to apply a rate limit to all HTTP methods ('*') on a given endpoint using 'SmartSurgeClient.set_rate_limit'. It configures a limit of 1000 requests per hour for 'https://api.example.com/data', regardless of the HTTP method used.

```Python
client.set_rate_limit(
    endpoint="https://api.example.com/data",
    method="*",  # Applies to all HTTP methods
    max_requests=1000,
    time_period=3600  # 1000 requests per hour
)
```

--------------------------------

### Initializing SmartSurge Client for Request History - Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

This snippet shows the basic initialization of the `SmartSurgeClient`. By default, the client tracks request history, which can be accessed later for debugging, logging, or analysis of past API interactions.

```python
from smartsurge import SmartSurgeClient

client = SmartSurgeClient()
```

--------------------------------

### Example Usage of RequestEntry in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/models.md

Provides practical examples of instantiating `RequestEntry` objects. It shows how to create a basic entry for a successful request and a more complex entry that includes rate limit information and response headers.

```python
from datetime import datetime, timezone
from smartsurge.models import RequestEntry, RequestMethod

# Basic entry
entry = RequestEntry(
    endpoint="/api/users",
    method=RequestMethod.GET,
    status_code=200,
    response_time=0.25,
    success=True
)

# Entry with rate limit info
entry = RequestEntry(
    endpoint="/api/data",
    method=RequestMethod.POST,
    status_code=429,
    response_time=0.1,
    success=False,
    max_requests=100,
    max_request_period=60.0,
    response_headers={"X-RateLimit-Limit": "100", "Retry-After": "30"}
)
```

--------------------------------

### Example: Downloading Files with Stream (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This snippet provides two examples of using the `stream` method: one for downloading a large file with resume support and a custom chunk size, and another for downloading a file without resume functionality. It demonstrates how to save files from a URL to a local path, highlighting the flexibility of the streaming feature.

```python
# Download with resume support
file_path = client.stream(
    "https://example.com/large-file.zip",
    "downloads/large-file.zip",
    chunk_size=1024*1024  # 1MB chunks
)

# Download without resume
file_path = client.stream(
    "https://example.com/data.csv",
    "data.csv",
    resume=False
)
```

--------------------------------

### HMMParams Configuration Examples - Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/hmm.md

Demonstrates how to instantiate `HMMParams` with default settings for a 3-state model and how to create a custom 4-state model by explicitly providing `n_states`, `initial_probs`, and `success_probs`. This illustrates flexible configuration of the HMM.

```python
# Default 3-state model
params = HMMParams()

# Custom 4-state model
params = HMMParams(
    n_states=4,
    initial_probs=np.array([0.7, 0.2, 0.08, 0.02]),
    success_probs=np.array([0.99, 0.85, 0.40, 0.10])
)
```

--------------------------------

### Initializing SmartSurge Client - With Base URL

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This snippet illustrates how to configure a SmartSurge client with a base URL. Setting a base URL simplifies subsequent requests by allowing the use of relative paths, reducing repetition for common API endpoints.

```python
# Set a base URL to avoid repeating it
client = SmartSurgeClient(base_url="https://api.github.com")

# Now use relative paths
response = client.get("/users/github")
response = client.get("/repos/python/cpython")
```

--------------------------------

### Setting Up a Basic SmartSurge Mock Server (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Demonstrates how to initialize and interact with a SmartSurge mock server using a pre-configured strict rate limit. It covers starting the server, making requests with a SmartSurge client, retrieving server metrics, and stopping the server.

```python
import smartsurge

if smartsurge.has_benchmarks():
    # Create a mock server with strict rate limiting
    config = smartsurge.get_strict_rate_limit_config()
    server = smartsurge.create_benchmark_server(config)
    
    # Start the server (runs in background thread)
    server_url = server.start()
    
    # Use with SmartSurge client
    client = smartsurge.SmartSurgeClient()
    response = client.get(f"{server_url}/api/endpoint")
    
    # Check server metrics
    metrics = server.get_metrics()
    print(f"Total requests: {metrics['total_requests']}")
    print(f"Rate limited: {metrics['rate_limited_requests']}")
    
    # Stop the server
    server.stop()
```

--------------------------------

### Basic Authentication with SmartSurge in Python

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

Provides examples of implementing Basic Authentication using 'HTTPBasicAuth' from 'requests.auth' or by passing a username/password tuple directly to the 'auth' parameter of a GET request with SmartSurgeClient. This allows for secure credential transmission.

```python
# Using auth parameter
from requests.auth import HTTPBasicAuth

response = client.get(
    "https://api.example.com/protected",
    auth=HTTPBasicAuth("username", "password")
)

# Or using tuple
response = client.get(
    "https://api.example.com/protected",
    auth=("username", "password")
)
```

--------------------------------

### Importing SmartSurge Utilities (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/index.md

This snippet shows how to import several utility functions and classes from SmartSurge, such as `SmartSurgeTimer` for performance timing and `configure_logging` for logging setup.

```python
from smartsurge import (
    SmartSurgeTimer,
    log_context,
    merge_histories,
    async_request_with_history,
    configure_logging
)
```

--------------------------------

### Using SmartSurge Benchmark Command Line Interface (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Provides examples of using the `smartsurge-benchmark` command-line tool to run different benchmark modes (demo, comprehensive, full, visualize) and apply additional options like `--pyperf` for statistical rigor or `--no-visualize`.

```bash
# Quick demonstration
smartsurge-benchmark --mode demo

# Comprehensive benchmark suite (default)
smartsurge-benchmark --mode comprehensive

# Full benchmark suite with all scenarios
smartsurge-benchmark --mode full

# Visualize existing results
smartsurge-benchmark --mode visualize

# Additional options
smartsurge-benchmark --comprehensive --pyperf --no-visualize
```

--------------------------------

### Complete RequestHistory Usage Example (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/models.md

This comprehensive example demonstrates the full lifecycle of using `RequestHistory` for intelligent rate limiting. It covers initialization, simulating requests, intercepting calls, logging responses, and observing the dynamic rate limit and search status updates, showcasing how `smartsurge` adapts to API behavior.

```Python
from smartsurge.models import (
    RequestMethod, RequestEntry, RequestHistory, 
    RateLimit, SearchStatus
)
from datetime import datetime, timezone
import time

# Create request history for tracking
history = RequestHistory(
    endpoint="/api/users",
    method=RequestMethod.GET,
    min_data_points=5  # Need at least 5 observations
)

# Simulate API requests
for i in range(15):
    # Intercept before request
    history.intercept_request()
    
    # Simulate making request
    time.sleep(0.1)  # Simulate network delay
    
    # Create entry based on response
    entry = RequestEntry(
        endpoint="/api/users",
        method=RequestMethod.GET,
        status_code=200 if i < 10 else 429,
        response_time=0.1,
        success=i < 10
    )
    
    # Log response
    history.log_response_and_update(entry)
    
    # Check status
    print(f"Request {i+1}: Status={history.search_status}")
    
    if history.rate_limit:
        print(f"Rate limit: {history.rate_limit}")
        print(f"Requests/sec: {history.rate_limit.get_requests_per_second():.2f}")
```

--------------------------------

### Setting Manual Rate Limits with SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/examples.md

Shows how to manually configure rate limits for specific API endpoints and HTTP methods using client.set_rate_limit(). The client then automatically respects these limits, pausing requests as needed to prevent exceeding the defined rate.

```python
from smartsurge import SmartSurgeClient
import time

# Create a client
client = SmartSurgeClient()

# Set rate limit for a specific endpoint
client.set_rate_limit(
    endpoint="https://api.example.com/items",
    method="GET",
    max_requests=5,
    time_period=1.0  # 5 requests per second
)

# Make multiple requests - will automatically respect rate limits
start_time = time.time()
for i in range(10):
    response = client.get(f"https://api.example.com/items/{i}")
    print(f"Request {i+1}: Status {response.status_code}")

end_time = time.time()
print(f"Total time: {end_time - start_time:.2f} seconds")
print("Should take ~2 seconds for 10 requests at 5 req/s")
```

--------------------------------

### Performing GET Requests with SmartSurge

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/basic_usage.md

This snippet shows how to perform GET requests using the SmartSurge client. It covers simple GET requests, adding query parameters to filter or paginate data, and including custom headers for authentication or other purposes.

```python
# Simple GET
response = client.get("https://api.example.com/users")

# With query parameters
response = client.get(
    "https://api.example.com/users",
    params={"page": 1, "limit": 10}
)

# With custom headers
response = client.get(
    "https://api.example.com/users/123",
    headers={"Authorization": "Bearer token123"}
)
```

--------------------------------

### Running HMM Performance Benchmark (Bash)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/benchmarks/BENCHMARKS.md

This snippet shows how to execute the HMM performance benchmarks to measure fitting time and memory usage. It provides a direct Python module execution command and an alternative using a shell script helper for convenience.

```bash
# Run performance benchmarks
python -m smartsurge.benchmarks.benchmark_hmm_performance

# Use the shell script helper
./src/smartsurge/benchmarks/run_hmm_benchmark.sh
```

--------------------------------

### Example: Removing a Rate Limit (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This example shows how to use `reset_rate_limit` to remove the rate limit previously set for the `/api/users` GET endpoint. This action effectively disables rate limiting for that specific combination, allowing unlimited requests until a new limit is set.

```python
# Remove rate limit
client.reset_rate_limit("/api/users", "GET")
```

--------------------------------

### Importing SmartSurge Mock Server Components (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/benchmark_usage.md

Imports essential classes and functions from the SmartSurge benchmark package for setting up and configuring a sophisticated mock server, including `BenchmarkMockServer`, `RateLimitConfig`, `RateLimitStrategy`, and `create_benchmark_server`.

```python
from smartsurge import (
    BenchmarkMockServer,      # Main mock server class
    RateLimitConfig,          # Configuration dataclass
    RateLimitStrategy,        # Enum of rate limiting strategies
    create_benchmark_server,  # Factory function
)
```

--------------------------------

### Setting Manual Rate Limits for Specific Endpoint and Method in SmartSurge (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/getting_started.md

This snippet demonstrates how to manually configure a rate limit for a specific API endpoint and HTTP method using 'SmartSurgeClient.set_rate_limit'. It sets a limit of 100 GET requests per minute for 'https://api.example.com/users'.

```Python
client = SmartSurgeClient()

# Set rate limit for a specific endpoint and method
client.set_rate_limit(
    endpoint="https://api.example.com/users",
    method="GET",
    max_requests=100,
    time_period=60  # 100 requests per minute
)
```

--------------------------------

### Example: Accessing Request History Details (Python)

Source: https://github.com/dingo-actual/smartsurge/blob/main/src/smartsurge/docs/api/client.md

This example shows how to use `get_request_history` to fetch and display statistics for the `/api/users` GET endpoint. If history exists, it prints the total number of requests, the success rate, and the average response time, providing insights into past API interactions.

```python
history = client.get_request_history("/api/users", "GET")
if history:
    print(f"Total requests: {len(history)}")
    print(f"Success rate: {history.success_rate():.2%}")
    print(f"Average response time: {history.avg_response_time():.3f}s")
```