getstacklens 0.0.1__tar.gz

getstacklens-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: ci
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -U pip
+      - run: pip install ruff
+      - run: ruff format --check .
+      - run: ruff check .
+
+  typecheck:
+    name: typecheck (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -U pip
+      - run: pip install ".[dev]" mypy
+      - run: mypy --ignore-missing-imports --show-error-codes getstacklens
+
+  test:
+    name: test (pytest, py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -U pip
+      - run: pip install ".[dev]"
+      - run: pytest -q
+
+  build:
+    name: build (sdist+wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -U pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+
+  security:
+    name: security (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -U pip
+      - run: pip install ".[dev]" pip-audit
+      - run: pip-audit

getstacklens-0.0.1/.github/workflows/codeql.yml

@@ -0,0 +1,25 @@
+name: codeql
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: analyze (codeql)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@v3

getstacklens-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write   # required to create GitHub releases
+  id-token: write   # required for PyPI trusted publishing
+
+jobs:
+  publish:
+    name: build, publish to PyPI, and create release
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - run: python -m pip install -U pip build
+
+      - name: build sdist and wheel
+        run: python -m build
+
+      - name: publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

getstacklens-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+
+# Build
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store

getstacklens-0.0.1/LICENSE

@@ -0,0 +1,31 @@
+StackLens Source-Available License
+
+Copyright (c) 2026 StackLens 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/stacklens-sdk-python
+
+NOT PERMITTED without prior written permission from StackLens 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 StackLens Private Limited and grant StackLens 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 STACKLENS, INC. BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE.

getstacklens-0.0.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: getstacklens
+Version: 0.0.1
+Summary: Python SDK for StackLens — 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: StackLens Source-Available License
+        
+        Copyright (c) 2026 StackLens 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/stacklens-sdk-python
+        
+        NOT PERMITTED without prior written permission from StackLens 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 StackLens Private Limited and grant StackLens 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 STACKLENS, 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
+
+# stacklens-sdk-python
+
+Python SDK for [StackLens](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 [StackLens 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 StackLens 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 StackLens 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)
+- [StackLens 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)

getstacklens-0.0.1/README.md

@@ -0,0 +1,136 @@
+# stacklens-sdk-python
+
+Python SDK for [StackLens](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 [StackLens 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 StackLens 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 StackLens 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)
+- [StackLens 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)