explainer-ai 0.4.1

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

Tapestry

An ML model evaluation and governance framework for production pipelines. Monitor traditional ML and generative AI systems with automated dashboarding, alerting, ground truth tracking, and a full model registry.

pip install explainer-ai

What It Does

Tapestry sits between your ML pipeline and your stakeholders. Models push predictions through Tapestry, which runs evaluators, tracks performance over time, fires alerts when things degrade, and renders governance dashboards — all backed by PostgreSQL.

ML Pipeline ──> Tapestry Evaluators ──> Database ──> Dashboards / Alerts
                     │                                     │
                     ├── Confidence, drift, SHAP            ├── Control Tower
                     ├── Hallucination, PHI, bias           ├── Per-model dashboards
                     ├── Ground truth matching               └── Slack/email alerts
                     └── Demographic fairness

Getting Started

1. Start PostgreSQL and initialize

If you don't have a PostgreSQL instance, use the included Docker Compose:

docker compose up -d

Then initialize Tapestry:

tapestry init --engine "postgresql://tapestry:tapestry@localhost:5432/tapestry"

This creates a fully-commented .tapestry.toml config file, initializes the database schema, and syncs evaluator definitions. If you have an existing PostgreSQL server, pass your own connection string instead.

2. Register your first model

The interactive wizard walks you through evaluator selection and optional governance metadata:

tapestry asset init

Or register from a JSON config file:

tapestry asset register -f my_model.json

3. Push data for evaluation

Via the REST API:

tapestry serve start

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}]}'

Or evaluate a local file directly:

tapestry evaluate my_model --file predictions.csv

4. Track performance

tapestry asset list                          # see all registered models
tapestry ground-truth status my_model        # check ground truth coverage
tapestry alerts check                        # evaluate alert rules
tapestry dashboard create-control-tower      # build governance dashboard

Features

Evaluation

• Traditional ML — confidence analysis, SHAP explainability, data drift (KS test), class distribution, entropy, run-over-run comparison, model validation from verified outcomes
• Generative AI — LLM-based judges for hallucination, fairness/bias, PHI detection, factual accuracy, traceability, prompt injection, audit readiness
• Demographic fairness — per-group pass rates, statistical fairness tests, and CHAI-aligned ground truth metrics (TPR, FPR, AUC, Brier score per subgroup)
• Evaluation dimensions — each evaluator maps to a dimension (performance, explainability, drift, stability, fairness, faithfulness, safety, compliance) for organized reporting

Ground Truth Monitoring

Predictions are logged automatically. Verified outcomes can arrive hours, days, or weeks later — Tapestry matches them and computes accuracy, F1, precision, recall, MAE, RMSE, and R² as ground truth becomes available.

tapestry ground-truth ingest my_model \
  --file reviewed_outcomes.csv \
  --ground-truth-column actual_label

Model Registry & Governance

Track model inventory, ownership, lifecycle, and impact commitments:

tapestry asset completeness                  # governance coverage scores
tapestry asset show-impact my_model          # ROI tracking vs. targets

Each asset can include inventory metadata (AI type, risk tier, deployment environment), ownership (model owner, clinical sponsor, escalation contact), lifecycle dates, and impact commitments with baseline/target values.

Alerting

Rule-based alerts on evaluation metrics with email, Slack, and webhook delivery:

# .tapestry.toml
[[alerts.rules]]
name = "low_pass_rate"
condition = "pass_rate_below"
threshold = 80.0
severity = "P1"
asset_key = "my_model"
channels = ["slack", "email"]

Available conditions: pass_rate_below, drift_score_above, staleness_days_above, ground_truth_coverage_below, model_performance_below, failure_count_above, consecutive_failures.

Dashboards

Automated Apache Superset dashboards:

tapestry dashboard create my_model           # per-asset dashboard
tapestry dashboard create-control-tower      # fleet-wide governance
tapestry dashboard create-comparison         # multi-model comparison
tapestry dashboard create-generative         # cross-asset LLM evaluation

The Control Tower provides a single view of your entire AI portfolio: overall pass rates, model quality scores, compliance status, drift trends, staleness tracking, alert history, and impact/ROI tracking.

REST API

Full API for programmatic access (interactive docs at /docs):

tapestry serve start                         # start in background

# Asset management
curl http://localhost:8084/api/v1/assets/
curl http://localhost:8084/api/v1/assets/my_model/health

# Data ingestion
curl -X POST http://localhost:8084/api/v1/assets/my_model/ingest \
  -H "Content-Type: application/json" \
  -d '{"data": [...]}'

# Ground truth
curl -X POST http://localhost:8084/api/v1/ground-truth \
  -H "Content-Type: application/json" \
  -d '{"asset_key": "my_model", "records": [...]}'

# Coverage & metrics
curl http://localhost:8084/api/v1/ground-truth/coverage?asset_key=my_model
curl http://localhost:8084/api/v1/metrics/summary?asset_key=my_model

Installation

pip install explainer-ai                     # core
pip install explainer-ai[api]                # REST API (FastAPI + uvicorn)
pip install explainer-ai[dagster]            # Dagster asset checks
pip install explainer-ai[superset]           # Superset dashboard support
pip install explainer-ai[full]               # everything

From source

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

Code Example

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

# Sample LLM outputs to evaluate
df = pd.DataFrame({
    "record_id": [1, 2, 3],
    "context": [
        "The patient is a 55-year-old male with hypertension.",
        "Lab results show A1c of 7.2%, 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%, excellent control.",           # hallucinated
        "The patient has a severe allergy to penicillin.",            # hallucinated
    ],
})

# Configure evaluators
config = TapestryConfig(
    identifier=["record_id"],
    asset_key="clinical_qa",
    custom_evaluators=[
        {"name": "hallucination", "arguments": {"model": "gpt-4o-mini"}},
        {"name": "phi_detection", "arguments": {"model": "gpt-4o-mini"}},
    ],
)

# Run evaluation
evaluator = GenerativeTapestry(config=config, backend="litellm")
results = evaluator.run(df)

# Write to database
db = TapestryDB.from_config()
evaluator.write_evaluators_to_db(results, db)

For local models, use any litellm-supported provider: {"model": "ollama/llama3", "api_base": "http://localhost:11434"}.

CLI Reference

Command	Description
Setup
tapestry init	Guided first-time setup (config, DB, evaluators)
tapestry doctor	Check project health (DB connection, config, etc.)
Assets
tapestry asset init	Interactive wizard to create an asset config
tapestry asset register -f <file>	Register assets from JSON file or directory
tapestry asset list	List all registered assets
tapestry asset show <key>	Show full config and governance details
tapestry asset completeness	Show governance completeness scores
tapestry asset show-impact <key>	Show impact commitments with ROI status
Evaluation
tapestry evaluate <asset> --file <csv>	Run evaluators on a local CSV
tapestry serve [start|stop|status|logs]	REST API server management
Ground Truth
tapestry ground-truth ingest <asset>	Match ground truth to predictions
tapestry ground-truth status <asset>	Show coverage and match latency
Alerts
tapestry alerts list	Show configured alert rules
tapestry alerts check	Evaluate all rules and fire notifications
tapestry alerts history	Show recent alert events
Dashboards
tapestry dashboard create <asset>	Per-asset Superset dashboard
tapestry dashboard create-control-tower	Governance overview dashboard
tapestry dashboard create-comparison	Multi-model comparison dashboard
Database
tapestry db init	Create schema and run migrations
tapestry db status	Show tables and row counts
tapestry db reset --force	Drop and recreate schema
tapestry migrate upgrade head	Run pending database migrations

All commands accept --schema/-s and --engine/-e overrides, or read from .tapestry.toml / environment variables.

Project Structure

src/tapestry/
    api/            # FastAPI REST API (routers, schemas, dependencies)
    alerts/         # Rule-based alert engine and delivery (email, Slack, webhook)
    cli/            # CLI commands (init, serve, asset, evaluate, ground-truth, etc.)
    core/           # Base classes, URI generation, demographics, retry logic
    db/             # SQLAlchemy models, migrations, schema management
    generative/     # LLM-based evaluators (litellm backend)
    models/         # Pydantic models for model registry / inventory
    monitoring/     # Ground truth metrics computation
    observability/  # OpenTelemetry integration
    superset/       # Dashboard builders, chart/view specs, Control Tower
    traditional/    # XGBoost, SHAP, drift, confidence evaluators
    config.py       # TapestryConfig, EvaluatorConfig, ScoreConfig
    registry.py     # Evaluator plugin registry with dimension mapping

Development

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

uv run pytest                               # run tests
uv run black --check src/ tests/            # format check
uv run ruff check src/ tests/               # lint
uv run mypy src/tapestry/                   # type check

Documentation

Full docs are available in docs/:

• Installation
• Quickstart
• Core Concepts
• Configuration
• Asset Registration
• REST API
• Generative Evaluators
• Traditional Evaluators
• Evaluation Dimensions
• Ground Truth Monitoring
• Model Registry
• Impact Tracking & ROI
• Superset Dashboards
• Alerting
• Dagster Integration
• Database Schema

License

See LICENSE for details.