explainer-ai 0.4.0

ML model evaluation and monitoring framework with explainability, fairness analysis, and Superset dashboards

Tapestry

An ML model evaluation and governance framework for production pipelines, supporting traditional ML and generative AI evaluation with automated dashboarding and alerting.

Features

• Traditional ML evaluation — confidence analysis, SHAP explainability, data drift, class distribution, entropy
• Generative AI evaluation — LLM-based judges for hallucination, fairness, PHI detection, factual accuracy, traceability, and more
• Demographic fairness — per-group pass rates, chi-squared tests, and CHAI-aligned ground truth metrics across demographic subgroups
• Automated Superset dashboards — per-asset, cross-asset generative, multi-model comparison, and Control Tower governance dashboards
• Alerting — rule-based alerts on evaluation metrics with Slack/email notification
• REST API — FastAPI-based API for data ingestion, evaluation, metrics, and asset management
• Dagster integration — optional asset checks for pipeline monitoring (pip install explainer-ai[dagster])
• Database persistence — PostgreSQL storage with migration support and URI-based record linking

Installation

pip install explainer-ai

# With optional extras
pip install explainer-ai[dagster]       # Dagster asset checks
pip install explainer-ai[superset]      # Superset dashboard support
pip install explainer-ai[full]          # All optional extras

Or with uv:

uv pip install explainer-ai
uv pip install explainer-ai[dagster,superset]

From source

git clone https://github.com/Cognome-Inc/tapestry.git
pip install ./tapestry

Quick Start

First-Time Setup

tapestry init --engine "postgresql://user:password@host:5432/database" --schema "tapestry_dev"

This creates a .env file, copies the example .tapestry.toml config, initializes the database schema, and syncs all built-in evaluator definitions.

You can also set up manually:

export TAPESTRY_ENGINE="postgresql://user:password@host:5432/database"
export TAPESTRY_SCHEMA="tapestry_dev"
tapestry db init

Generative Evaluation

This example evaluates a small dataset for hallucinations using an OpenAI model. Set your OPENAI_API_KEY environment variable, then copy this into a script and run it.

import pandas as pd
from datetime import datetime
from tapestry.config import TapestryConfig
from tapestry.generative.tapestry import GenerativeTapestry
from tapestry import TapestryDB

# 1. Sample data — each row has a context and an LLM response to evaluate
df = pd.DataFrame({
    "record_id": [1, 2, 3],
    "context": [
        "The patient is a 55-year-old male with a history of hypertension.",
        "Lab results show hemoglobin A1c of 7.2%, indicating poorly controlled diabetes.",
        "The patient reported no known drug allergies.",
    ],
    "raw_model_response": [
        "The patient is a 55-year-old male with hypertension.",           # faithful
        "Lab results show A1c of 5.0%, indicating excellent control.",    # hallucinated
        "The patient has a severe allergy to penicillin.",                # hallucinated
    ],
})

# 2. Configure — pick which evaluators to run and which LLM judges them
config = TapestryConfig(
    identifier=["record_id"],
    asset_key="readme_example",
    custom_evaluators=[
        {"name": "hallucination", "arguments": {"model": "gpt-4o-mini"}},
    ],
    batch_size=10,
)

# 3. Run evaluation
evaluator = GenerativeTapestry(config=config, backend="litellm")
results = evaluator.run(df)
print(results[["record_id", "HallucinationDetection", "HallucinationDetection reasoning"]])

# 4. (Optional) Write results to the database
# Reads engine/schema from .tapestry.toml or TAPESTRY_ENGINE/TAPESTRY_SCHEMA env vars
db = TapestryDB.from_config()
evaluator.write_evaluators_to_db(results, db)

For other providers, change the arguments — e.g. {"model": "ollama/llama3", "api_base": "http://localhost:11434"} for local Ollama models.

REST API

Start the API server and push data for evaluation:

# Start the server
tapestry serve

# Register an asset with its evaluator config (one-time)
curl -X POST http://localhost:8084/api/v1/assets/ \
  -H "Content-Type: application/json" \
  -d '{
    "asset_key": "my_model",
    "evaluator_type": "traditional",
    "identifier_columns": ["record_id"],
    "config": {
      "custom_evaluators": [
        {"name": "confidence-analysis", "arguments": {"predicted_class_column": "pred", "confidence_score_column": "score", "model_id": "v1", "threshold": 0.9}}
      ]
    }
  }'

# Push data for evaluation (repeatable — config is stored)
curl -X POST http://localhost:8084/api/v1/assets/my_model/ingest \
  -H "Content-Type: application/json" \
  -d '{"data": [{"record_id": "1", "pred": "A", "score": 0.95}]}'

# Query results
curl http://localhost:8084/api/v1/assets/my_model/health

Interactive API docs are available at http://localhost:8084/docs.

Dashboards

# Per-asset dashboard
tapestry dashboard create <asset_key>

# Cross-asset generative evaluation (with demographic fairness tab)
tapestry dashboard create-generative

# Multi-model comparison
tapestry dashboard create-comparison

# Governance Control Tower
tapestry dashboard create-control-tower

Requires a .tapestry.toml with Superset connection details. All commands support --dry-run to create SQL views only.

Offline Evaluation

Run evaluators against a local CSV file without the REST API:

tapestry evaluate my_model --file predictions.csv \
  --evaluator model-validation \
  --verified-outcome-column actual_label \
  --predicted-column predicted_label \
  --confidence-column confidence

CLI Reference

Command	Description
tapestry init	Guided first-time setup (.env, config, DB)
tapestry db init	Create schema and run migrations
tapestry db status	Show tables, row counts, migration status
tapestry db sync-checks	Sync evaluator definitions to the database
tapestry db reset --force	Drop and recreate schema
tapestry asset register -f <file>	Register assets from JSON config file or directory
tapestry asset list	List all registered assets
tapestry asset show <key>	Show full config for a registered asset
tapestry asset delete <key>	Remove an asset registration
tapestry evaluate <asset> --file <csv>	Run evaluators on a local CSV file
tapestry serve	Start the REST API server
tapestry dashboard create <asset>	Per-asset Superset dashboard
tapestry dashboard create-generative	Cross-asset generative dashboard
tapestry dashboard create-comparison	Multi-model comparison dashboard
tapestry dashboard create-control-tower	Governance overview dashboard
tapestry migrate upgrade head	Run pending migrations
tapestry migrate autogenerate -m "msg"	Generate migration from model changes

All commands accept --schema/-s and --engine/-e overrides.

Project Structure

src/tapestry/
    api/            # FastAPI REST API (routers, schemas, dependencies)
    core/           # Base classes, URI generation, demographics
    traditional/    # XGBoost + SHAP evaluation
    generative/     # LLM-based evaluators (litellm)
    db/             # SQLAlchemy models, migrations
    superset/       # Dashboard builders, chart/view specs
    cli/            # CLI commands (serve, db, dashboard, alerts, migrate)
    config.py       # TapestryConfig, EvaluatorConfig, ScoreConfig
    registry.py     # Evaluator registry

Development

For contributing to Tapestry itself, clone the repo and install from source:

git clone https://github.com/Cognome-Inc/tapestry.git
cd tapestry
uv sync --dev --extra full

uv run pytest                               # Run tests
uv run black .                              # Format code
uv run ruff check src/ tests/               # Lint

Documentation

See docs/ for full documentation:

• Getting Started
• REST API
• Asset Registration
• Configuration
• Generative Evaluators
• Traditional Evaluators
• Demographic Fairness
• Superset Dashboards
• Database Schema
• Alerting
• Dagster Integration