decimalai 0.3.0__tar.gz

decimalai-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+
+    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: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install ruff
+
+      - name: Check formatting
+        run: ruff check decimalai/ --select I,E,W,F --ignore E501

decimalai-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # Required for Trusted Publisher (OIDC)
+  contents: read
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    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: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    name: Publish to PyPI
+    needs: test  # Only publish if tests pass
+    runs-on: ubuntu-latest
+    environment: pypi  # Optional: use GitHub Environment for approvals
+
+    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 package
+        run: python -m build
+
+      - name: Verify package version matches release tag
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ Version mismatch: pyproject.toml=$PKG_VERSION, tag=$TAG_VERSION"
+            exit 1
+          fi
+          echo "✅ Version match: $PKG_VERSION"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API token needed — uses Trusted Publisher (OIDC)

decimalai-0.3.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example

decimalai-0.3.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: decimalai
+Version: 0.3.0
+Summary: Open source SDK for agent dataset lifecycle management
+Project-URL: Homepage, https://github.com/decimal-labs/decimalai-python
+Project-URL: Documentation, https://docs.decimal.ai
+Project-URL: Repository, https://github.com/decimal-labs/decimalai-python
+Author: Decimal AI
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: langgraph>=0.1; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1; extra == 'langgraph'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# DecimalAI Python SDK
+
+The open source SDK for [Decimal AI](https://decimal.ai) — the dataset control plane for agents.
+
+## Installation
+
+```bash
+pip install decimal-ai
+```
+
+With framework integrations:
+```bash
+pip install "decimal-ai[langchain]"   # LangChain/LangGraph
+pip install "decimal-ai[openai]"      # OpenAI SDK
+pip install "decimal-ai[all]"         # All integrations
+```
+
+## Quick Start
+
+```python
+import decimalai
+
+decimalai.init(api_key="dai_sk_...")
+
+# LangChain/LangGraph — add callback handler
+from decimalai.langchain import CallbackHandler
+
+llm = ChatOpenAI(model="gpt-4o", callbacks=[CallbackHandler()])
+```
+
+## What It Does
+
+- **Trace capture** — Auto-captures LLM calls, tool calls, and agent steps
+- **Version spec extraction** — Auto-detects tool schemas, prompts, models, and graph topology
+- **Change detection** — Detects when your agent configuration changes
+- **Replay helpers** — Pull and submit replay tasks for data rescue
+- **Dataset export** — Export clean JSONL/parquet for fine-tuning
+
+## License
+
+MIT

decimalai-0.3.0/README.md

@@ -0,0 +1,41 @@
+# DecimalAI Python SDK
+
+The open source SDK for [Decimal AI](https://decimal.ai) — the dataset control plane for agents.
+
+## Installation
+
+```bash
+pip install decimal-ai
+```
+
+With framework integrations:
+```bash
+pip install "decimal-ai[langchain]"   # LangChain/LangGraph
+pip install "decimal-ai[openai]"      # OpenAI SDK
+pip install "decimal-ai[all]"         # All integrations
+```
+
+## Quick Start
+
+```python
+import decimalai
+
+decimalai.init(api_key="dai_sk_...")
+
+# LangChain/LangGraph — add callback handler
+from decimalai.langchain import CallbackHandler
+
+llm = ChatOpenAI(model="gpt-4o", callbacks=[CallbackHandler()])
+```
+
+## What It Does
+
+- **Trace capture** — Auto-captures LLM calls, tool calls, and agent steps
+- **Version spec extraction** — Auto-detects tool schemas, prompts, models, and graph topology
+- **Change detection** — Detects when your agent configuration changes
+- **Replay helpers** — Pull and submit replay tasks for data rescue
+- **Dataset export** — Export clean JSONL/parquet for fine-tuning
+
+## License
+
+MIT

decimalai-0.3.0/decimalai/__init__.py

@@ -0,0 +1,298 @@
+"""DecimalAI SDK — Agent dataset lifecycle platform.
+
+Quick start::
+
+    import decimalai
+    decimalai.init()  # reads DECIMAL_API_KEY from env
+
+    # LangChain — one-liner
+    decimalai.init(langchain=True)
+
+    # Or manual install
+    from decimalai.langchain import install
+    install()
+
+    # Generic / any framework
+    @decimalai.trace(agent_name="my-agent")
+    def run_agent(query):
+        decimalai.log_llm_call(model="gpt-4o", input=msgs, output=resp)
+        return resp.choices[0].message.content
+"""
+
+__version__ = "0.3.0"
+
+import logging
+import os
+from typing import Optional
+
+logger = logging.getLogger("decimalai")
+
+
+def init(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    project: Optional[str] = None,
+    enabled: bool = True,
+    langchain: bool = False,
+    agent_name: Optional[str] = None,
+) -> None:
+    """Initialize the DecimalAI SDK.
+
+    Must be called once before using any integration. Configuration is
+    resolved in order: explicit parameter → environment variable → default.
+
+    Args:
+        api_key: API key. Falls back to ``DECIMAL_API_KEY`` env var.
+        base_url: Backend URL. Falls back to ``DECIMAL_BASE_URL``, then
+            ``https://api.decimal.ai``.
+        project: Optional project grouping.
+        enabled: Set ``False`` to disable all tracing (integrations become no-ops).
+        langchain: If ``True``, auto-calls ``decimalai.langchain.install()``.
+        agent_name: Default agent name for langchain auto-install.
+
+    Raises:
+        DecimalConfigError: If ``api_key`` is not provided and not in env.
+    """
+    from ._config import DecimalConfig, DecimalConfigError
+    from ._client import DecimalAIClient
+
+    import decimalai._config as _cfg
+
+    # Resolve API key
+    resolved_key = api_key or os.environ.get("DECIMAL_API_KEY", "")
+    if not resolved_key and enabled:
+        raise DecimalConfigError(
+            "No API key provided. Pass api_key= to decimalai.init() "
+            "or set the DECIMAL_API_KEY environment variable."
+        )
+
+    # Resolve base URL
+    resolved_url = (
+        base_url
+        or os.environ.get("DECIMAL_BASE_URL", "")
+        or "https://api.decimal.ai"
+    )
+
+    config = DecimalConfig(
+        api_key=resolved_key,
+        base_url=resolved_url.rstrip("/"),
+        project=project,
+        enabled=enabled,
+    )
+    _cfg._config = config
+
+    if enabled:
+        _cfg._client = DecimalAIClient(
+            api_key=config.api_key,
+            base_url=config.base_url,
+            project=config.project,
+        )
+        logger.info(
+            "DecimalAI SDK initialized: base_url=%s project=%s",
+            config.base_url,
+            config.project,
+        )
+    else:
+        _cfg._client = None
+        logger.info("DecimalAI SDK initialized in disabled mode (no-op)")
+
+    # Auto-install langchain tracing if requested
+    if langchain:
+        from .langchain import install as _lc_install
+        _lc_install(agent_name=agent_name)
+
+
+def send(trace) -> None:
+    """Manually send a trace to the backend.
+
+    For advanced usage when ``auto_send=False``.
+    """
+    from ._config import _get_client
+
+    client = _get_client()
+    client.ingest_trace(trace)
+
+
+# ── Eval convenience functions ─────────────────────────────────
+
+
+def eval(
+    trace_id: str,
+    name: str,
+    score: float,
+    *,
+    source: str = "custom",
+    source_label: Optional[str] = None,
+    passed: Optional[bool] = None,
+    reason: Optional[str] = None,
+    category: str = "quality",
+) -> dict:
+    """Push a single eval score to a trace.
+
+    This is the simplest way to attach evaluation results to a trace.
+    All scores are visible in the dashboard's Evaluation Breakdown card
+    grouped by source.
+
+    Args:
+        trace_id: The trace to attach the score to.
+        name: Metric name (e.g., "factual_accuracy", "coherence").
+        score: Score value between 0.0 and 1.0.
+        source: Eval source identifier. Defaults to "custom".
+        source_label: Human-readable display name (e.g., "My RAG Eval").
+        passed: Binary pass/fail. Defaults to score >= 0.5.
+        reason: Human-readable explanation of the score.
+        category: "quality" (default) or "compatibility".
+
+    Returns:
+        API response with stored score details and recomputed verdict.
+
+    Example::
+
+        import decimalai
+        decimalai.init()
+
+        decimalai.eval(
+            trace_id="abc123",
+            name="factual_accuracy",
+            score=0.75,
+            reason="3/4 facts verified against source docs",
+        )
+    """
+    from ._config import _get_client
+
+    client = _get_client()
+    score_entry = {
+        "name": name,
+        "score": score,
+        "passed": passed if passed is not None else score >= 0.5,
+    }
+    if reason:
+        score_entry["reason"] = reason
+
+    metadata = {}
+    if source_label:
+        metadata["source_label"] = source_label
+
+    return client.push_eval_scores(
+        trace_id=trace_id,
+        source=source,
+        scores=[score_entry],
+    )
+
+
+def score(
+    trace_id: str,
+    name: str,
+    value: float,
+    reason: Optional[str] = None,
+) -> dict:
+    """Shorthand for pushing a single eval score.
+
+    Args:
+        trace_id: The trace to attach the score to.
+        name: Metric name.
+        value: Score between 0.0 and 1.0.
+        reason: Optional explanation.
+
+    Returns:
+        API response.
+
+    Example::
+
+        decimalai.score("abc123", "factual_accuracy", 0.75)
+    """
+    return eval(
+        trace_id=trace_id,
+        name=name,
+        score=value,
+        reason=reason,
+    )
+
+
+def get_eval_breakdown(trace_id: str) -> dict:
+    """Get the full eval breakdown for a trace with provenance info.
+
+    Returns scores grouped by source (Manifest Diff, DeepEval, LangSmith,
+    Custom, etc.) with icons, labels, and decision reasons.
+
+    Returns:
+        Dict with eval_verdict, quality_avg, compat_avg, source_groups,
+        and decision_reasons.
+
+    Example::
+
+        import decimalai
+        decimalai.init()
+
+        bd = decimalai.get_eval_breakdown("abc123")
+        print(f"Verdict: {bd['eval_verdict']}")
+    """
+    from ._config import _get_client
+
+    client = _get_client()
+    return client.get_eval_breakdown(trace_id)
+
+
+# ── Re-export generic tracing API ──────────────────────────────
+
+from .generic import (  # noqa: E402, F401
+    log_llm_call,
+    log_tool_call,
+    start_trace,
+    trace,
+)
+
+# Re-export eval adapters from new location
+from .evals.adapters import (  # noqa: E402, F401
+    push_deepeval_results,
+    push_langsmith_scores,
+    push_custom_scores,
+)
+
+from .evals import batch_eval  # noqa: E402, F401
+
+__all__ = [
+    "__version__",
+    "init",
+    "send",
+    "eval",
+    "score",
+    "get_eval_breakdown",
+    "trace",
+    "start_trace",
+    "log_llm_call",
+    "log_tool_call",
+    "push_deepeval_results",
+    "push_langsmith_scores",
+    "push_custom_scores",
+    "batch_eval",
+]
+
+
+# ── Auto-init from environment variable ────────────────────────
+# Setting DECIMAL_AUTO_TRACE=langchain will auto-init and install tracing.
+
+def _auto_init_from_env() -> None:
+    """Auto-initialize from environment variables if configured."""
+    auto_trace = os.environ.get("DECIMAL_AUTO_TRACE", "").strip().lower()
+    if not auto_trace:
+        return
+
+    api_key = os.environ.get("DECIMAL_API_KEY", "")
+    if not api_key:
+        logger.debug(
+            "DECIMAL_AUTO_TRACE=%s set but no DECIMAL_API_KEY found, skipping",
+            auto_trace,
+        )
+        return
+
+    try:
+        init(
+            langchain=(auto_trace == "langchain"),
+        )
+        logger.info("DecimalAI auto-initialized via DECIMAL_AUTO_TRACE=%s", auto_trace)
+    except Exception:
+        logger.debug("Auto-init failed", exc_info=True)
+
+
+_auto_init_from_env()