Metadata-Version: 2.4
Name: getstacklens
Version: 0.1.0
Summary: Python SDK for GetStackLens — observability and governance for your AI stack
Project-URL: Homepage, https://getstacklens.ai
Project-URL: Documentation, https://getstacklens.ai/docs
Project-URL: Repository, https://github.com/getstacklens-ai/stacklens-sdk-python
Project-URL: Bug Tracker, https://github.com/getstacklens-ai/stacklens-sdk-python/issues
License: GetStackLens Source-Available License
        
        Copyright (c) 2026 GetStackLens Private Limited. All rights reserved.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated files (the "Software"), to use and run it
        for personal or commercial purposes, subject to the following conditions:
        
        PERMITTED:
        - Using and running the Software as-is
        - Integrating the Software into your own applications
        - Reading and referencing the source code
        - Submitting corrections or improvements via pull request to the official
          repository at https://github.com/getstacklens-ai/stacklens-sdk-python
        
        NOT PERMITTED without prior written permission from GetStackLens Private Limited:
        - Modifying or creating derivative works based on the Software
        - Redistributing the Software, in whole or in part
        - Sublicensing the Software
        - Selling the Software or incorporating it into a competing product or service
        - Publishing a fork or modified copy of the Software
        
        CONTRIBUTIONS:
        All contributions submitted via pull request are made under the terms of this
        license. By submitting a pull request, you agree to transfer copyright of your
        contribution to GetStackLens Private Limited and grant GetStackLens Private Limited the right to use,
        modify, and publish your contribution under any license.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED. IN NO EVENT SHALL GETSTACKLENS, INC. BE LIABLE FOR ANY CLAIM, DAMAGES,
        OR OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE.
License-File: LICENSE
Keywords: ai,governance,llm,observability,prompt-management,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# GetStackLens Python SDK

Python SDK for [GetStackLens](https://getstacklens.ai) — observability and governance for your AI stack.

Trace LLM calls, fetch versioned prompts, and enforce AI governance policies — in three lines of Python.

## Installation

```bash
pip install getstacklens
```

Requires Python 3.9+.

## Quickstart

```python
import getstacklens

getstacklens.configure(api_key="sl-xxxx")
getstacklens.trace("my-llm-call", model="gpt-4o", provider="openai", input_tokens=150, output_tokens=200)
```

Get your API key from the [GetStackLens dashboard](https://app.getstacklens.ai) under **Settings → API Keys**.

## Tracing LLM calls

### Simple trace (one line)

For accurate latency, record `start_time` before the call and pass it in:

```python
from datetime import datetime, timezone
import getstacklens

getstacklens.configure(api_key="sl-xxxx")

start = datetime.now(timezone.utc)
response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarise this document."}],
)
getstacklens.trace(
    "chat-completion",
    model="gpt-4o",
    provider="openai",
    input_tokens=response.usage.prompt_tokens,
    output_tokens=response.usage.completion_tokens,
    start_time=start,
)
```

### Context manager (recommended for agent workflows)

```python
import openai
import getstacklens

getstacklens.configure(api_key="sl-xxxx")
client = openai.OpenAI()

with getstacklens.start_trace("customer-support-agent") as span:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "How do I reset my password?"}],
    )
    span.record_llm(
        model="gpt-4o",
        provider="openai",
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
        completion=response.choices[0].message.content,
    )
    span.set_attribute("user_id", "u_123")
    span.add_tag("support", "production")
```

If an exception is raised inside the context, the span status is automatically set to `error`.

## Fetching versioned prompts (FlowOps)

Manage prompts in the GetStackLens dashboard, then fetch them at runtime — no deploys needed.

```python
import getstacklens

getstacklens.configure(api_key="sl-xxxx")

# Fetch the active prompt for the production environment
system_prompt = getstacklens.prompts.get("support-system-prompt", env="production")

# Use in an LLM call
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_message},
    ],
)
```

Available environments: `"dev"`, `"staging"`, `"production"` (default).

## Self-hosted deployments

Point the SDK at your own GetStackLens instance:

```python
getstacklens.configure(
    api_key="sl-xxxx",
    endpoint="https://api.your-domain.com",
)
```

See the [self-hosting guide](https://getstacklens.ai/docs/self-hosting) for setup instructions.

## Supported providers

Works with any LLM provider — pass the model and provider name you use:

| Provider | `provider` value |
|---|---|
| OpenAI | `"openai"` |
| Anthropic | `"anthropic"` |
| Google Gemini | `"gemini"` |
| Azure OpenAI | `"azure-openai"` |
| AWS Bedrock | `"bedrock"` |
| Any other | any string |

## Links

- [Documentation](https://getstacklens.ai/docs)
- [GetStackLens Platform](https://getstacklens.ai)
- [Dashboard](https://app.getstacklens.ai)
- [GitHub](https://github.com/getstacklens-ai/stacklens-sdk-python)
- [Report an issue](https://github.com/getstacklens-ai/stacklens-sdk-python/issues)
