REFERENCE / API SURFACE

The interfaces behind the workflow.

DATADOC has one source of truth: the fitted pipeline. The CLI, Python SDK, and local UI all call the same domain objects and enforce the same safety rules.

DataDocPipelinePipelineConfigDataDocError

Start with the SDK →

Domain objects

Object	Purpose	Important fields
`PipelineConfig`	Controls target, task, policy, split columns, and resource behavior.	`target`, `task`, `scaling`, `strict_schema`
`DatasetProfile`	Describes schema, quality findings, roles, and fingerprint.	`roles`, `findings`, `null_counts`
`TransformPlan`	Ordered, explainable transformation operations.	`operations`, `protected_columns`
`EvaluationReport`	Compares the baseline and selected preparation choice.	`metric`, `split_strategy`, `improvement`
`AIExplanation`	Structured AI feature hypotheses, missingness analysis, and config recommendation.	`summary`, `missingness_mechanisms`, `feature_hypotheses`
`DataDocError`	Actionable compatibility and input-contract failure.	message text identifies the failing column or option

Pythonpublic imports
from datadoc import DataDocPipeline, PipelineConfig
from datadoc.core.pipeline import (
    DataDocError,
    DatasetProfile,
    EvaluationReport,
    TransformPlan,
)
from datadoc.ai import AIExplainer, AIExplanation, explain_dataset

Pipeline methods

METHODpipeline.profile(df)

Returns a DatasetProfile. Read-only and safe before fit.

METHODpipeline.plan(df)

Returns a TransformPlan with operations, findings, and protected columns.

METHODpipeline.fit(train_df, target=None)

Fits train-only state and returns the same pipeline instance.

METHODpipeline.transform(df)

Validates schema and applies frozen state. Raises DataDocError when the input contract fails.

METHODpipeline.save(path) / DataDocPipeline.load(path)

Serialize and restore an artifact. Save only after fit; load before inference.

METHODpipeline.evaluate(df, target=None)

Runs the optional scikit-learn benchmark. Requires datadoc-cli[ml] and a non-null target. estimator_family="both" fits linear and tree models and keeps the stronger validation score.

METHODpipeline.evaluate_ablation(df, target=None)

Compares full, no-clip, no-scaling, and minimal variants. Powers datadoc evaluate --ablation.

METHODpipeline.drift_report(df)

Schema validation plus median-shift drift issues. Powers datadoc transform --validate and GET /api/pipeline/drift.

METHODpipeline.explain_plan(df)

Human-readable English trace of the plan. Powers datadoc plan --explain.

AI METHODdatadoc.ai.explain_dataset(file_path, target=None, model=None)

Generates structured feature engineering hypotheses, missingness classifications (MCAR/MAR/MNAR), and target leakage audit using LiteLLM.

METHODpipeline.profile_to_html(df=None)

Small HTML profile widget for Jupyter and marimo notebooks.

METHODpipeline.export_sklearn_artifact(path)

Saves a joblib artifact dict. Powers datadoc export --format joblib.

Local UI API endpoints

The FastAPI UI uses a local session header. The browser should not create a second transformation implementation.

Endpoint	Input	Returns
`GET /api/dataset/metadata`	`X-DATADOC-SESSION`	Loaded file, row/column counts, metadata.
`GET /api/pipeline/profile`	Optional `target`	Serialized profile.
`POST /api/pipeline/plan`	Pipeline request JSON	Serialized plan.
`POST /api/pipeline/fit`	Pipeline request JSON	Fitted flag, profile, plan, input/output schema.
`GET /api/pipeline/preview`	Session header	Output schema and preview rows (8 rows).
`GET /api/pipeline/export/code`	Session header	Text Python wrapper (executable: `python pipeline.py in.csv out.csv`).
`GET /api/pipeline/lineage`	Session header	Train provenance, input/output schema, config, plan operations.
`GET /api/pipeline/drift`	Session header	Schema check plus median-shift drift issues for numeric columns.
`GET /api/dataset/report`	Session header	Standalone, self-contained HTML audit report.
`GET /api/dataset/compare`	Session header	Side-by-side comparison metrics (raw vs transformed).
`GET /api/dataset/export/csv`	Session header	Transformed CSV download (or raw data before fit).

JavaScriptUI request shape
await axios.post("/api/pipeline/fit", {
  target: "churn",
  task: "auto",                       // auto | classification | regression
  scaling: "auto",                     // auto | none | standard | robust
  drop_identifiers: false,
  deduplicate: false,
  clip_outliers: false,
  categorical_threshold: 20,
  rare_category_min_frequency: 0.0,
  datetime_cyclical: false,
  datetime_extract_hour: true,
}, {
  headers: { "X-DATADOC-SESSION": "local" },
});

Error contract

422 validation error

Use when task, scaling, target, file type, or pipeline configuration is invalid. The response detail should tell the user what to change.

400 state error

Use when a session exists but a pipeline has not been fitted—for example, requesting a preview before clicking Fit.

404 session error

Use when the session header does not map to an initialized local job.

Pythonconsumer-side handling
try:
  transformed = pipeline.transform(rows)
except DataDocError as error:
  # Log the artifact version and input schema before retrying.
  raise RuntimeError(f"Input contract failed: {error}") from error