crystil 0.8.0__tar.gz

crystil-0.8.0/CONTRIBUTE.md

@@ -0,0 +1,138 @@
+# Python SDK
+
+The Python SDK allows customers who have a Python solution to integrate with Crystil. Below are steps to get the SDK working on your local environment. Since we are a Python shop, this is the 1st SDK that gets updated, and this is the SDK we use to test with most.
+
+## Supports
+
+Currently the Python SDK supports the following LLM Clients:
+
+- Anthropic version 0.76.0 - Official version from Anthropic
+- Google GenAI - Official version from Google
+- Groq version 1.2.0 - Runs many open source LLMs
+- LangChain version 0.3.27 - Works with LangChain framework that works with many LLMs
+- Open AI version 2.15.0 - Official version from Open AI
+- Pydantic version 0.8.1 - Works with Pydantic framework that works with many LLMs
+
+## Prerequisites
+
+### Install UV
+
+The Python SDK uses UV as the package/project manager, so if you don't already have this installed, install it.
+
+```bash
+brew install uv
+```
+
+## Install Python SDK
+
+Get the source code:
+
+```bash
+cd ~/src/payloop
+git clone git@github.com:CrystilAI/python-sdk.git
+cd ~/src/payloop/python-sdk
+```
+
+Install dependencies and create venv:
+
+```bash
+uv sync
+```
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+To run integration tests, you need to add the following keys/credentials to the environment. Note you can just set a subset of these keys if you just want to test some of the integrations.
+
+```bash
+cp .env.example .env
+```
+
+- **ANTHROPIC_API_KEY** - Valid Anthropic LLM key used for Anthropic tests.
+- **AWS_ACCESS_KEY_ID** - The AWS access key used for LangChain Bedrock tests.
+- **AWS_SECRET_ACCESS_KEY** - The AWS secret access key used for LangChain Bedrock tests.
+- **AWS_DEFAULT_REGION** - The AWS default region used for LangChain Bedrock tests. Currently it is `us-east-1`.
+- **GOOGLE_APPLICATION_CREDENTIALS** - Local path to your Google credentials file. This is used for LangChain Google and Vertex tests.
+- **GOOGLE_API_KEY** - Google API Key used for Google tests.
+- **GROQ_API_KEY** - Groq API Key used for Groq tests.
+- **OPENAI_API_KEY** - Valid OpenAI LLM key used for OpenAI tests.
+- **OPENROUTER_API_KEY** - Valid Open Router AI key used to test Pydantic AI.
+- **CRYSTIL_API_KEY** - Crystil API key. Log into desired environment (production, staging, or local) and get the production API key there.
+
+Run integration tests:
+
+```bash
+uv run pytest --integration
+```
+
+## GitHub Actions Workflows
+
+Shortly after Python SDK `0.6.0` was released, we added GitHub Actions workflows for running both unit tests and integration tests.
+
+In the GitHub free plan, you have limits on GitHub Actions usage:
+https://docs.github.com/en/billing/concepts/product-billing/github-actions#free-use-of-github-actions
+
+As of this writing, the free plan has 2,000 minutes available per month and 10 GB of cache storage.
+
+Unit and integration test runs will be counted against the minutes available.
+
+If the Crystil GitHub account starts running low on available minutes (at 80% usage), an email will be sent to GitHub account administrators.
+
+### Unit test suite runs
+
+Unit tests will run upon:
+
+- Every push to a branch that has a PR opened
+- Every push to `main`
+
+This "Run Unit Tests" workflow is defined in this file:
+https://github.com/CrystilAI/backend/blob/main/.github/workflows/run-tests.yml
+
+Upon these events, any pytest tests NOT marked with `@pytest.mark.integration` will be run.
+
+Any tests marked with `@pytest.mark.integration` will ONLY run as part of the integration test suite.
+
+Unit tests will NOT run for any branch whose PR title has `[WIP]` present. This allows us to not run the tests on a branch that's actively in development, which allows us to save on GitHub Actions minutes usage.
+
+The unit tests are run against Python versions 3.9, 3.10, 3.11, 3.12, and 3.13.
+
+As of this writing, some Python packages that we depend on have not been updated for Python 3.14. Python 3.14 was released in October 2025. Apparently it's common for Python packages to not be updated until 6-12 months after releases.
+
+#### Viewing unit test suite runs in GitHub UI
+
+The GitHub Actions page for the Python SDK can be found at:
+https://github.com/CrystilAI/python-sdk/actions
+
+### Integration test suite runs
+
+The integration test suite is run against the Crystil staging environment. It will perform real LLM SDK calls, which will be sent along to the staging Collector.
+
+The "Run Integration Tests" workflow is defined in this file:
+https://github.com/CrystilAI/python-sdk/blob/main/.github/workflows/run-integration-tests.yaml
+
+> **The integration test suite will run only when manually requested by a user!**
+
+This was a deliberate choice because the integration test suite:
+
+- Takes longer to run
+- Performs LLM requests
+- Sends Crystil collector requests to the staging environment
+
+Because performing LLM requests incurs a cost, we only want to run integration tests when the developer has specifically requested to run them.
+
+#### Running integration tests
+
+You should generally run the integration tests at these points in time:
+
+- Before merging a branch of Python SDK changes to `main` — this ensures that your Python SDK changes are working with the current branch running in staging
+- If you have made `backend` repository changes that may impact SDK usage, and deployed them to the staging environment — you can run the integration tests from the `main` branch of Python SDK against staging
+
+1. To run the integration tests, visit [the Actions page](https://github.com/CrystilAI/python-sdk/actions).
+2. Click "Run Integration Tests"
+3. Click "Run workflow" button
+4. Select branch to run from (`main` or branch for your outstanding PR)
+5. See updated Actions list
+6. Monitor progress via the topmost "Run Integration Tests" workflow

crystil-0.8.0/MANIFEST.in

@@ -0,0 +1,14 @@
+prune tests
+prune .claude
+prune .github
+prune bin
+exclude CLAUDE.md
+exclude CLAUDE.local.md
+exclude .pre-commit-config.yaml
+exclude .python-version
+exclude .env
+exclude .env.example
+exclude .gitignore
+exclude uv.lock
+global-exclude __pycache__
+global-exclude *.py[cod]

crystil-0.8.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: crystil
+Version: 0.8.0
+Summary: Crystil Python SDK
+Author-email: Crystil <noc@crystil.com>
+Project-URL: Homepage, https://crystil.com/
+Project-URL: Documentation, https://developers.crystil.com/
+Project-URL: Repository, https://github.com/CrystilAI/
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: botocore
+Requires-Dist: grpcio
+Requires-Dist: protobuf
+Requires-Dist: requests
+Requires-Dist: urllib3
+
+# Welcome to Crystil!
+
+### Cost Visibility for AI Agents
+
+Crystil is a lightweight infrastructure layer that gives AI teams real-time visibility into the true costs of deploying agents - across tasks, workflows, and customers. Most teams today can’t see what it actually costs to deploy their agents, making it nearly impossible to manage gross margins or price with confidence.
+
+With just a single line of code, Crystil delivers:
+- Cost tracking across OpenAI, Anthropic, Gemini, Groq, and more in one place
+- Breakdowns by task, agent, and customer in real time
+- Confidence to deploy the right pricing model (cost-plus, token-based, outcome-based, etc.) while preserving gross margins
+
+Watch a short demo video: [Crystil Walkthrough Video](https://www.youtube.com/watch?v=Z-GkSl_7imY)
+
+By surfacing exactly what’s driving cost and value, Crystil becomes the source of truth for agent economics - helping founders and operators scale their agents with confidence.
+
+Sign up here: [crystil.com](https://crystil.com/)
+
+# Installation
+
+    pip install crystil
+
+# Documentation
+
+Our SDK reference provides documentation for:
+- Understanding how Crystil works
+- Demonstrating how to integrate Crystil into your product
+- Code samples to illustrate our SDK and API
+
+Check it out here: [developers.crystil.com](https://developers.crystil.com)

crystil-0.8.0/README.md

@@ -0,0 +1,29 @@
+# Welcome to Crystil!
+
+### Cost Visibility for AI Agents
+
+Crystil is a lightweight infrastructure layer that gives AI teams real-time visibility into the true costs of deploying agents - across tasks, workflows, and customers. Most teams today can’t see what it actually costs to deploy their agents, making it nearly impossible to manage gross margins or price with confidence.
+
+With just a single line of code, Crystil delivers:
+- Cost tracking across OpenAI, Anthropic, Gemini, Groq, and more in one place
+- Breakdowns by task, agent, and customer in real time
+- Confidence to deploy the right pricing model (cost-plus, token-based, outcome-based, etc.) while preserving gross margins
+
+Watch a short demo video: [Crystil Walkthrough Video](https://www.youtube.com/watch?v=Z-GkSl_7imY)
+
+By surfacing exactly what’s driving cost and value, Crystil becomes the source of truth for agent economics - helping founders and operators scale their agents with confidence.
+
+Sign up here: [crystil.com](https://crystil.com/)
+
+# Installation
+
+    pip install crystil
+
+# Documentation
+
+Our SDK reference provides documentation for:
+- Understanding how Crystil works
+- Demonstrating how to integrate Crystil into your product
+- Code samples to illustrate our SDK and API
+
+Check it out here: [developers.crystil.com](https://developers.crystil.com)

crystil-0.8.0/crystil/__init__.py

@@ -0,0 +1,102 @@
+r"""
+  ___             _   _ _
+ / __|_ _ _  _ __| |_(_) |
+| (__| '_| || (_-<  _| | |
+ \___|_|  \_, /__/\__|_|_|AI
+          |__/                             07312025 / optimus codex
+"""
+
+import os
+from uuid import uuid4
+
+from crystil._config import Config
+from crystil._errors import CrystilRequestInterceptedError
+from crystil._providers import Anthropic as LlmProviderAnthropic
+from crystil._providers import Google as LlmProviderGoogle
+from crystil._providers import Groq as LlmProviderGroq
+from crystil._providers import LangChain as LlmProviderLangChain
+from crystil._providers import OpenAi as LlmProviderOpenAi
+from crystil._providers import PydanticAi as LlmProviderPydanticAi
+from crystil._sentinel import Sentinel
+from crystil.api._workflow import Workflow, Workflows
+
+__all__ = ["Crystil", "CrystilRequestInterceptedError"]
+
+
+class Crystil:
+    def __init__(self, api_key=None):
+        if api_key is None:
+            api_key = os.environ.get("CRYSTIL_API_KEY", None)
+
+        if api_key is None:
+            raise RuntimeError(
+                "API key is missing. Either set the CRYSTIL_API_KEY environment "
+                + "variable or set the api_key parameter when instantiating Crystil."
+            )
+
+        self.config = Config()
+        self.config.api_key = api_key
+        self.config.tx_uuid = uuid4()
+        self.sentinel = Sentinel(self.config)
+
+        self.anthropic = LlmProviderAnthropic(self)
+        self.google = LlmProviderGoogle(self)
+        self.groq = LlmProviderGroq(self)
+        self.langchain = LlmProviderLangChain(self)
+        self.openai = LlmProviderOpenAi(self)
+        self.pydantic_ai = LlmProviderPydanticAi(self)
+
+        self.workflow = Workflow(self.config)
+        self.workflows = Workflows(self.config)
+
+    def attribution(
+        self,
+        parent_id=None,
+        parent_name=None,
+        subsidiary_id=None,
+        subsidiary_name=None,
+        # -- Deprecated parameters! They are here for backwards compatibility only.
+        parent_uuid=None,
+        subsidiary_uuid=None,
+    ):
+        if parent_id is None:
+            raise RuntimeError("a string parent_id is required")
+
+        parent_id = str(parent_id)
+
+        if len(parent_id) > 100:
+            raise RuntimeError("parent_id cannot be greater than 100 characters")
+
+        if parent_name is not None and len(parent_name) > 100:
+            raise RuntimeError("parent_name cannot be greater than 100 characters")
+
+        if subsidiary_name is not None and subsidiary_id is None:
+            raise RuntimeError(
+                "a string subsidiary_id is required if a subsidiary_name is provided"
+            )
+
+        if subsidiary_id is not None:
+            subsidiary_id = str(subsidiary_id)
+
+            if len(subsidiary_id) > 100:
+                raise RuntimeError(
+                    "subsidiary_id cannot be greater than 100 characters"
+                )
+
+        if subsidiary_name is not None and len(subsidiary_name) > 100:
+            raise RuntimeError("subsidiary_name cannot be greater than 100 characters")
+
+        subsidiary = None
+        if subsidiary_id is not None:
+            subsidiary = {"id": subsidiary_id, "name": subsidiary_name}
+
+        self.config.attribution = {
+            "parent": {"id": parent_id, "name": parent_name},
+            "subsidiary": subsidiary,
+        }
+
+        return self
+
+    def new_transaction(self):
+        self.config.tx_uuid = uuid4()
+        return self