canary-ops-sdk 0.1.0__tar.gz

canary_ops_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-asyncio
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write  # for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

canary_ops_sdk-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.egg
+MANIFEST
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover

canary_ops_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- Initial release: Python SDK for Canary AI Security.
+- **`Canary`** class — main client with background batch flushing, redaction, firewall, and cost auto-computation.
+- **`track_prompt()`**, **`track_response()`**, **`track_tool_call()`**, **`track_error()`** — telemetry event tracking.
+- **`scan(prompt)`** — local + remote prompt firewall returning a `ScanResult`.
+- **`guard(prompt)`** — raises `CanaryBlockedError` on blocked prompts.
+- **`scan_response(text)`** — output-side guardrails: secret/PII regex + remote LLM-as-judge.
+- **`plant_token()`** — synthetic canary token generation; auto-detected by `scan_response`.
+- **`scan_context(docs)`** — parallel RAG document scanning (OWASP LLM04).
+- **`trace(name)`** — context manager for recording arbitrary async steps as spans.
+- **`wrap_fetch(fn)`** — decorator wrapping any callable with latency + error tracking.
+- **`wrap_openai(client)`** — instrument `openai.OpenAI` / `openai.AsyncOpenAI` (sync + streaming + async).
+- **`wrap_anthropic(client)`** — instrument `anthropic.Anthropic` / `anthropic.AsyncAnthropic` (sync + streaming + async).
+- **19 local threat patterns** — ported from JS SDK: injection, jailbreak, system-prompt extraction, data exfiltration, leet-speak / encoding evasion.
+- **Redaction engine** — masks/hashes/removes secrets (OpenAI, AWS, GitHub, Anthropic, Slack, Google, bearer tokens, JWTs, private keys) and optional PII (email, phone, SSN, credit card, IP).
+- **Auto cost** — built-in pricing table for OpenAI, Anthropic, Gemini, Bedrock, and Mistral models.
+- **Resilient transport** — `urllib`-based HTTP with retry + exponential backoff + jitter + circuit breaker.
+- Zero runtime dependencies. Python 3.8+.

canary_ops_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: canary-ops-sdk
+Version: 0.1.0
+Summary: The Operating System for AI Security — monitor, secure, and audit every AI agent and LLM application in production.
+Project-URL: Homepage, https://canary-ops.base44.app
+Project-URL: Repository, https://github.com/CryptoSuess/canary-sdk-python
+Project-URL: Bug Tracker, https://github.com/CryptoSuess/canary-sdk-python/issues
+Project-URL: Changelog, https://github.com/CryptoSuess/canary-sdk-python/blob/main/CHANGELOG.md
+Author: CryptoSuess & Txnchi
+License: MIT
+Keywords: agent-monitoring,ai-firewall,ai-security,canary,llm,llmops,observability,prompt-injection,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# canary-ops-sdk
+
+**The Operating System for AI Security** — Python SDK for monitoring, securing, and auditing every AI agent and LLM application in production.
+
+Zero-dependency telemetry, redaction, and firewall SDK. Works with any Python LLM library.
+
+[![PyPI](https://img.shields.io/pypi/v/canary-ops-sdk)](https://pypi.org/project/canary-ops-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/canary-ops-sdk)](https://pypi.org/project/canary-ops-sdk/)
+
+---
+
+## Install
+
+```bash
+pip install canary-ops-sdk
+```
+
+No runtime dependencies. Python 3.8+.
+
+---
+
+## Quick start
+
+```python
+from canary_ops import Canary
+
+canary = Canary(
+    api_key="sk-canary-...",   # from your Canary dashboard
+    agent_id="my-agent",
+)
+
+# Manual tracking
+canary.track_prompt("What is the capital of France?", model="gpt-4o")
+canary.track_response("Paris.", model="gpt-4o", tokens_in=10, tokens_out=3)
+canary.track_tool_call("web_search", {"query": "Paris"}, {"results": [...]})
+
+canary.flush()  # or call shutdown() at process exit
+```
+
+---
+
+## OpenAI instrumentation
+
+```python
+from openai import OpenAI
+from canary_ops import Canary
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+client = canary.wrap_openai(OpenAI())
+
+# All chat completions are now tracked automatically
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+Streaming is also supported — just pass `stream=True`.
+
+---
+
+## Anthropic instrumentation
+
+```python
+import anthropic
+from canary_ops import Canary
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+client = canary.wrap_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-opus-4-5",
+    messages=[{"role": "user", "content": "Hello!"}],
+    max_tokens=256,
+)
+```
+
+---
+
+## Prompt firewall
+
+```python
+from canary_ops import Canary, CanaryBlockedError, ScanOptions
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+
+# scan() — returns a ScanResult, never raises
+result = canary.scan(user_prompt, ScanOptions(remote=False))
+if not result.allowed:
+    return "I can't help with that."
+
+# guard() — raises CanaryBlockedError if the prompt is blocked
+try:
+    safe_prompt = canary.guard(user_prompt)
+except CanaryBlockedError as e:
+    print(f"Blocked: {e.scan_result.threats}")
+```
+
+---
+
+## Output scanning
+
+```python
+# Scan a response for leaked secrets, PII, or exfiltration
+from canary_ops import ScanResponseOptions
+
+result = canary.scan_response(
+    llm_output,
+    ScanResponseOptions(throw_on_unsafe=True),
+)
+```
+
+---
+
+## Canary tokens
+
+```python
+# Plant a decoy credential in your agent's context
+token = canary.plant_token()
+system_prompt = f"Company API key: {token.token_value}\n{your_context}"
+
+# If the token appears in any response, Canary fires a data_exfiltration alert
+result = canary.scan_response(response_text)
+```
+
+---
+
+## RAG context scanning
+
+```python
+from canary_ops import ScanContextOptions
+
+docs = retriever.get_relevant_documents(query)
+results = canary.scan_context(
+    [d.page_content for d in docs],
+    ScanContextOptions(concurrency=5),
+)
+safe_docs = [d for d, r in zip(docs, results) if r.allowed]
+```
+
+---
+
+## Configuration reference
+
+```python
+from canary_ops import Canary, GuardConfig, RedactionConfig, RetryConfig
+
+canary = Canary(
+    api_key="sk-canary-...",
+    agent_id="my-agent",
+    # Privacy
+    capture_content=True,          # set False for metadata-only mode
+    max_content_length=10_000,     # truncate long prompts
+    redaction=RedactionConfig(
+        secrets=True,              # strip API keys, tokens, private keys
+        pii=True,                  # strip emails, phones, SSNs, credit cards
+        mode="mask",               # "mask" | "hash" | "remove"
+    ),
+    sample_rate=0.5,               # only send 50% of events
+    # Firewall
+    guard=GuardConfig(
+        local=True,                # run in-process heuristics
+        remote=True,               # call the remote deep scanner
+        block_on_local=True,       # short-circuit on high-confidence local hit
+        responses=False,           # auto-scan every LLM response
+    ),
+    fail_open=True,                # allow prompts if the remote scanner is unreachable
+    # Resilience
+    timeout_ms=10_000,
+    retry=RetryConfig(retries=3, backoff_ms=250),
+    # Batching
+    flush_interval_ms=5_000,       # drain queue every 5 s
+    max_batch_size=20,             # flush immediately when queue hits 20
+    # Hooks
+    before_send=lambda event: event,   # inspect/mutate/drop events
+    on_error=lambda exc: print(exc),   # custom error handler
+    # Tagging
+    environment="production",
+    release="v1.2.3",
+    debug=False,
+)
+```
+
+---
+
+## Error reference
+
+| Exception | When it's raised |
+|---|---|
+| `CanaryBlockedError` | `guard()` or `scan_response(..., throw_on_unsafe=True)` when the firewall blocks |
+| `CanaryApiError` | `plant_token()` when the API call fails |
+| `CanaryNotInitializedError` | Calling SDK methods before `Canary(...)` is constructed |
+
+`CanaryBlockedError` carries a `.scan_result` attribute with the full `ScanResult`.
+
+---
+
+## Async support
+
+All wrapper patching detects whether the underlying client's `create` method is a coroutine and patches it with an async wrapper automatically. The `Canary` client itself is thread-safe; background flushing runs on a daemon thread.
+
+---
+
+## License
+
+MIT © CryptoSuess & Txnchi

canary_ops_sdk-0.1.0/README.md

@@ -0,0 +1,206 @@
+# canary-ops-sdk
+
+**The Operating System for AI Security** — Python SDK for monitoring, securing, and auditing every AI agent and LLM application in production.
+
+Zero-dependency telemetry, redaction, and firewall SDK. Works with any Python LLM library.
+
+[![PyPI](https://img.shields.io/pypi/v/canary-ops-sdk)](https://pypi.org/project/canary-ops-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/canary-ops-sdk)](https://pypi.org/project/canary-ops-sdk/)
+
+---
+
+## Install
+
+```bash
+pip install canary-ops-sdk
+```
+
+No runtime dependencies. Python 3.8+.
+
+---
+
+## Quick start
+
+```python
+from canary_ops import Canary
+
+canary = Canary(
+    api_key="sk-canary-...",   # from your Canary dashboard
+    agent_id="my-agent",
+)
+
+# Manual tracking
+canary.track_prompt("What is the capital of France?", model="gpt-4o")
+canary.track_response("Paris.", model="gpt-4o", tokens_in=10, tokens_out=3)
+canary.track_tool_call("web_search", {"query": "Paris"}, {"results": [...]})
+
+canary.flush()  # or call shutdown() at process exit
+```
+
+---
+
+## OpenAI instrumentation
+
+```python
+from openai import OpenAI
+from canary_ops import Canary
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+client = canary.wrap_openai(OpenAI())
+
+# All chat completions are now tracked automatically
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+Streaming is also supported — just pass `stream=True`.
+
+---
+
+## Anthropic instrumentation
+
+```python
+import anthropic
+from canary_ops import Canary
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+client = canary.wrap_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-opus-4-5",
+    messages=[{"role": "user", "content": "Hello!"}],
+    max_tokens=256,
+)
+```
+
+---
+
+## Prompt firewall
+
+```python
+from canary_ops import Canary, CanaryBlockedError, ScanOptions
+
+canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+
+# scan() — returns a ScanResult, never raises
+result = canary.scan(user_prompt, ScanOptions(remote=False))
+if not result.allowed:
+    return "I can't help with that."
+
+# guard() — raises CanaryBlockedError if the prompt is blocked
+try:
+    safe_prompt = canary.guard(user_prompt)
+except CanaryBlockedError as e:
+    print(f"Blocked: {e.scan_result.threats}")
+```
+
+---
+
+## Output scanning
+
+```python
+# Scan a response for leaked secrets, PII, or exfiltration
+from canary_ops import ScanResponseOptions
+
+result = canary.scan_response(
+    llm_output,
+    ScanResponseOptions(throw_on_unsafe=True),
+)
+```
+
+---
+
+## Canary tokens
+
+```python
+# Plant a decoy credential in your agent's context
+token = canary.plant_token()
+system_prompt = f"Company API key: {token.token_value}\n{your_context}"
+
+# If the token appears in any response, Canary fires a data_exfiltration alert
+result = canary.scan_response(response_text)
+```
+
+---
+
+## RAG context scanning
+
+```python
+from canary_ops import ScanContextOptions
+
+docs = retriever.get_relevant_documents(query)
+results = canary.scan_context(
+    [d.page_content for d in docs],
+    ScanContextOptions(concurrency=5),
+)
+safe_docs = [d for d, r in zip(docs, results) if r.allowed]
+```
+
+---
+
+## Configuration reference
+
+```python
+from canary_ops import Canary, GuardConfig, RedactionConfig, RetryConfig
+
+canary = Canary(
+    api_key="sk-canary-...",
+    agent_id="my-agent",
+    # Privacy
+    capture_content=True,          # set False for metadata-only mode
+    max_content_length=10_000,     # truncate long prompts
+    redaction=RedactionConfig(
+        secrets=True,              # strip API keys, tokens, private keys
+        pii=True,                  # strip emails, phones, SSNs, credit cards
+        mode="mask",               # "mask" | "hash" | "remove"
+    ),
+    sample_rate=0.5,               # only send 50% of events
+    # Firewall
+    guard=GuardConfig(
+        local=True,                # run in-process heuristics
+        remote=True,               # call the remote deep scanner
+        block_on_local=True,       # short-circuit on high-confidence local hit
+        responses=False,           # auto-scan every LLM response
+    ),
+    fail_open=True,                # allow prompts if the remote scanner is unreachable
+    # Resilience
+    timeout_ms=10_000,
+    retry=RetryConfig(retries=3, backoff_ms=250),
+    # Batching
+    flush_interval_ms=5_000,       # drain queue every 5 s
+    max_batch_size=20,             # flush immediately when queue hits 20
+    # Hooks
+    before_send=lambda event: event,   # inspect/mutate/drop events
+    on_error=lambda exc: print(exc),   # custom error handler
+    # Tagging
+    environment="production",
+    release="v1.2.3",
+    debug=False,
+)
+```
+
+---
+
+## Error reference
+
+| Exception | When it's raised |
+|---|---|
+| `CanaryBlockedError` | `guard()` or `scan_response(..., throw_on_unsafe=True)` when the firewall blocks |
+| `CanaryApiError` | `plant_token()` when the API call fails |
+| `CanaryNotInitializedError` | Calling SDK methods before `Canary(...)` is constructed |
+
+`CanaryBlockedError` carries a `.scan_result` attribute with the full `ScanResult`.
+
+---
+
+## Async support
+
+All wrapper patching detects whether the underlying client's `create` method is a coroutine and patches it with an async wrapper automatically. The `Canary` client itself is thread-safe; background flushing runs on a daemon thread.
+
+---
+
+## License
+
+MIT © CryptoSuess & Txnchi

canary_ops_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "canary-ops-sdk"
+version = "0.1.0"
+description = "The Operating System for AI Security — monitor, secure, and audit every AI agent and LLM application in production."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [{name = "CryptoSuess & Txnchi"}]
+keywords = [
+    "canary",
+    "ai-security",
+    "llm",
+    "observability",
+    "telemetry",
+    "ai-firewall",
+    "prompt-injection",
+    "agent-monitoring",
+    "llmops",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://canary-ops.base44.app"
+Repository = "https://github.com/CryptoSuess/canary-sdk-python"
+"Bug Tracker" = "https://github.com/CryptoSuess/canary-sdk-python/issues"
+Changelog = "https://github.com/CryptoSuess/canary-sdk-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/canary_ops"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.8"
+strict = true
+ignore_missing_imports = true

canary_ops_sdk-0.1.0/src/canary_ops/__init__.py

@@ -0,0 +1,65 @@
+"""
+canary-ops-sdk — The Operating System for AI Security.
+
+Quick start::
+
+    from canary_ops import Canary
+
+    canary = Canary(api_key="sk-canary-...", agent_id="my-agent")
+    canary.track_prompt("Hello, world!")
+    canary.flush()
+"""
+from ._client import (
+    Canary,
+    CanaryApiError,
+    CanaryBlockedError,
+    CanaryNotInitializedError,
+)
+from ._types import (
+    CanaryConfig,
+    CanaryToken,
+    DetectedThreat,
+    FirewallAction,
+    GuardConfig,
+    PlantTokenOptions,
+    RedactionConfig,
+    RetryConfig,
+    ScanContextOptions,
+    ScanOptions,
+    ScanResponseOptions,
+    ScanResult,
+    TelemetryEvent,
+    TokenType,
+)
+from .instrument import wrap_anthropic, wrap_openai
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main client
+    "Canary",
+    # Errors
+    "CanaryNotInitializedError",
+    "CanaryBlockedError",
+    "CanaryApiError",
+    # Types
+    "CanaryConfig",
+    "TelemetryEvent",
+    "ScanResult",
+    "ScanOptions",
+    "ScanResponseOptions",
+    "PlantTokenOptions",
+    "ScanContextOptions",
+    "CanaryToken",
+    "TokenType",
+    "DetectedThreat",
+    "FirewallAction",
+    "RedactionConfig",
+    "GuardConfig",
+    "RetryConfig",
+    # Standalone instrumentors
+    "wrap_openai",
+    "wrap_anthropic",
+    # Version
+    "__version__",
+]