jack-data-science-agent 4.1.0__py3-none-any.whl

data_science_agent/__init__.py

@@ -0,0 +1,30 @@
+__version__ = "4.1.0"
+
+from data_science_agent.sdk import (
+    Agent,
+    Analysis,
+    Artifact,
+    Benchmark,
+    BenchmarkResult,
+    Dataset,
+    Evidence,
+    Insight,
+    Report,
+    Reproduction,
+    ReproductionResult,
+)
+
+__all__ = [
+    "Agent",
+    "Analysis",
+    "Artifact",
+    "Benchmark",
+    "BenchmarkResult",
+    "Dataset",
+    "Evidence",
+    "Insight",
+    "Report",
+    "Reproduction",
+    "ReproductionResult",
+    "__version__",
+]

data_science_agent/sdk.py

@@ -0,0 +1,658 @@
+"""Data Science Agent — Public SDK (W2 Distribution Hardening).
+
+Public surface (§14): ``Agent, Dataset, Analysis, Evidence, Artifact, Benchmark, Reproduction``
+plus stable companions ``Insight, Report, BenchmarkResult, ReproductionResult``.
+
+Stability (§15 / §18): see :data:`API_STABILITY`. Only ``data_science_agent.*`` is public;
+``dsa_agent``, ``dsa_tools`` etc. are ``Internal`` — public code must not import ``_internal``.
+
+Each Stable API below documents: Description / Parameters / Return Value / Errors / Example / Version (§16).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Dataset:
+    """A dataset handle for SDK calls.
+
+    Description:
+        Lightweight handle pointing to a local dataset file. Stable since 4.0.0.
+
+    Parameters:
+        path: Filesystem path to CSV/Parquet dataset.
+        dataset_id: Optional logical id (defaults to file stem).
+        rows: Populated after profiling if available.
+        cols: Populated after profiling if available.
+
+    Return Value:
+        ``Dataset`` instance.
+
+    Errors:
+        No I/O on construction; ``Agent.profile`` / ``Agent.analyze`` may raise
+        ``FileNotFoundError`` or ``ValueError`` for unsupported format.
+
+    Example:
+        >>> from data_science_agent import Dataset
+        >>> ds = Dataset.from_path("benchmarks/v2/datasets/sales.csv")
+        >>> ds.dataset_id
+        'sales'
+
+    Version:
+        4.0.0 Stable
+    """
+
+    path: str
+    dataset_id: str | None = None
+    rows: int | None = None
+    cols: int | None = None
+
+    @classmethod
+    def from_path(cls, path: str | Path) -> Dataset:
+        """Create a Dataset from a filesystem path.
+
+        Parameters:
+            path: Path to dataset file.
+
+        Return Value:
+            ``Dataset`` with ``path`` and ``dataset_id`` set to stem.
+
+        Errors:
+            Never raises for missing file (deferred to ``Agent``).
+
+        Example:
+            >>> Dataset.from_path("sales.csv").path
+            'sales.csv'
+
+        Version:
+            4.0.0 Stable
+        """
+        p = Path(path)
+        return cls(path=str(p), dataset_id=p.stem)
+
+
+@dataclass
+class Evidence:
+    """Evidence grounding an insight (Insight → Evidence → ToolCall → Dataset).
+
+    Description:
+        Evidence record produced by a tool call. Stable since 4.0.0.
+
+    Parameters:
+        id: Evidence id (e.g. ``ev-...``).
+        claim: Natural-language claim backed by this evidence.
+        source_type: One of ``sql|python|statistical_test|model|visualization``.
+        source_id: ToolCall id or artifact id backing the claim.
+        result: Tool output dict (JSON-serializable).
+        confidence: 0.0–1.0.
+        validation_status: ``pending|validated|rejected``.
+
+    Return Value:
+        ``Evidence`` dataclass.
+
+    Errors:
+        Construction never raises; validation happens in ``Analysis.validation``.
+
+    Example:
+        >>> from data_science_agent import Evidence
+        >>> e = Evidence(id="ev-1", claim="price~revenue r=0.9", source_type="python", source_id="tc-1")
+        >>> e.confidence
+        0.0
+
+    Version:
+        4.0.0 Stable
+    """
+
+    id: str
+    claim: str
+    source_type: str
+    source_id: str
+    result: dict[str, Any] = field(default_factory=dict)
+    confidence: float = 0.0
+    validation_status: str = "pending"
+
+
+@dataclass
+class Artifact:
+    """Artifact produced during analysis (chart, table, report, etc.).
+
+    Description:
+        Pointer to a file artifact under ``artifacts/reports/<run_id>/``. Stable.
+
+    Parameters:
+        id: Artifact id.
+        type: ``dataset|code|sql|table|chart|model|notebook|report|evidence``.
+        path: Relative or absolute path.
+        metadata: Free-form metadata (e.g. ``{rows: 500}``).
+        created_by: Creator (default ``agent``).
+        created_at: ISO-8601 timestamp or None.
+
+    Return Value:
+        ``Artifact`` instance.
+
+    Errors:
+        None on construction.
+
+    Example:
+        >>> Artifact(id="a-1", type="chart", path="artifacts/reports/run-1/chart.png")
+        Artifact(...)
+
+    Version:
+        4.0.0 Stable
+    """
+
+    id: str
+    type: str
+    path: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_by: str = "agent"
+    created_at: str | None = None
+
+
+@dataclass
+class Insight:
+    """Insight derived from evidence.
+
+    Description:
+        High-level finding linked to one or more ``Evidence`` ids. Stable.
+
+    Parameters:
+        id: Insight id.
+        finding: Natural-language finding.
+        evidence_ids: List of backing evidence ids.
+        limitation: Optional limitation note.
+        magnitude: Optional magnitude (e.g. ``large``).
+        significance: Optional significance (e.g. ``p<0.01``).
+
+    Return Value:
+        ``Insight`` instance.
+
+    Errors:
+        None.
+
+    Example:
+        >>> Insight(id="in-1", finding="Revenue correlates with price", evidence_ids=["ev-1"])
+
+    Version:
+        4.0.0 Stable
+    """
+
+    id: str
+    finding: str
+    evidence_ids: list[str] = field(default_factory=list)
+    limitation: str | None = None
+    magnitude: str | None = None
+    significance: str | None = None
+
+
+@dataclass
+class Analysis:
+    """Result of ``Agent.analyze``.
+
+    Description:
+        Complete analysis result: status, report, evidence, insights, artifacts,
+        tool_calls, validation, error, and raw_state. Stable.
+
+    Parameters:
+        run_id: Unique run id (``run-...``).
+        status: ``COMPLETED|FAILED|...`` (mirrors ``AnalysisState.status``).
+        report_markdown: Report markdown if generated.
+        evidence: List of ``Evidence``.
+        insights: List of ``Insight``.
+        artifacts: List of ``Artifact``.
+        tool_calls: Raw tool call dicts (JSON-serializable).
+        validation: Validation result dicts.
+        error: Error message if failed else None.
+        raw_state: Original ``AnalysisState`` (Internal, may be None).
+
+    Return Value:
+        ``Analysis`` aggregate.
+
+    Errors:
+        ``Agent.analyze`` raises ``FileNotFoundError`` for missing dataset,
+        ``ValueError`` for empty task.
+
+    Example:
+        >>> from data_science_agent import Agent
+        >>> r = Agent().analyze_sync("benchmarks/v2/datasets/sales.csv", "Analyze revenue")
+        >>> r.status
+        'COMPLETED'
+
+    Version:
+        4.0.0 Stable
+    """
+
+    run_id: str
+    status: str
+    report_markdown: str | None = None
+    evidence: list[Evidence] = field(default_factory=list)
+    insights: list[Insight] = field(default_factory=list)
+    artifacts: list[Artifact] = field(default_factory=list)
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    validation: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+    raw_state: Any = None
+
+
+API_STABILITY: dict[str, str] = {
+    "Agent": "Stable",
+    "Dataset": "Stable",
+    "Analysis": "Stable",
+    "Evidence": "Stable",
+    "Artifact": "Stable",
+    "Insight": "Stable",
+    "Report": "Stable",
+    "Benchmark": "Stable",
+    "Reproduction": "Stable",
+    "BenchmarkResult": "Stable",
+    "ReproductionResult": "Stable",
+}
+
+
+class Agent:
+    """Stable SDK facade (W2) over Core Engine (graph + evidence). [Stable]
+
+    Description:
+        Primary entrypoint for analyses. Wraps ``dsa_agent.graph.run_analysis``
+        (LangGraph Planner→Scientist→Critic→Report) and exposes async and sync
+        variants. Stable since 4.0.0; async behavior is cancellation-friendly.
+
+    Parameters:
+        None on construction; methods take dataset + task.
+
+    Return Value:
+        Constructed ``Agent`` with ``version == "4.0.0"``.
+
+    Errors:
+        Methods may raise ``FileNotFoundError`` (missing dataset),
+        ``ValueError`` (empty task / unsupported format).
+
+    Example:
+        >>> from data_science_agent import Agent, Dataset
+        >>> agent = Agent()
+        >>> result = agent.analyze_sync(Dataset.from_path("sales.csv"), "Analyze revenue")
+        >>> result.evidence[0].claim  # doctest: +SKIP
+
+    Version:
+        4.0.0 Stable
+    """
+
+    def __init__(self) -> None:
+        self._version = "4.1.0"
+
+    async def analyze(
+        self,
+        dataset: str | Path | Dataset,
+        task: str,
+        *,
+        run_id: str | None = None,
+    ) -> Analysis:
+        """Run an analysis (async).
+
+        Description:
+            Execute the agent graph for a dataset + natural-language task.
+            Returns evidence-grounded ``Analysis`` (report + evidence + artifacts).
+
+        Parameters:
+            dataset: Path string / ``Path`` / ``Dataset`` handle.
+            task: Natural-language question (non-empty).
+            run_id: Optional explicit run id for reproducibility.
+
+        Return Value:
+            ``Analysis`` with ``status`` (COMPLETED), ``report_markdown``,
+            ``evidence``, ``insights``, ``artifacts``, ``tool_calls``.
+
+        Errors:
+            ``FileNotFoundError`` if dataset missing; ``ValueError`` if task empty.
+
+        Example:
+            >>> import asyncio
+            >>> from data_science_agent import Agent
+            >>> asyncio.run(Agent().analyze("sales.csv", "Analyze revenue"))  # doctest: +SKIP
+
+        Version:
+            4.0.0 Stable
+        """
+        from dsa_agent.graph import run_analysis
+
+        if isinstance(dataset, Dataset):
+            ds_path = dataset.path
+            ds_id = dataset.dataset_id or Path(ds_path).stem if ds_path else dataset.dataset_id or "dataset"
+        else:
+            ds_path = str(dataset)
+            ds_id = Path(ds_path).stem if ds_path else "dataset"
+
+        state = await run_analysis(dataset_path=ds_path, dataset_id=ds_id, user_query=task, run_id=run_id)
+        return Analysis(
+            run_id=state.run_id,
+            status=state.status.value if hasattr(state.status, "value") else str(state.status),
+            report_markdown=state.report_markdown,
+            evidence=[Evidence(**e.model_dump()) for e in state.evidence] if state.evidence and hasattr(state.evidence[0], "model_dump") else [Evidence(**dict(e)) for e in state.evidence],
+            insights=[Insight(**i.model_dump()) for i in state.insights] if state.insights and hasattr(state.insights[0], "model_dump") else [Insight(**dict(i)) for i in state.insights],
+            artifacts=[Artifact(**a.model_dump()) for a in state.artifacts] if state.artifacts and hasattr(state.artifacts[0], "model_dump") else [Artifact(**dict(a)) for a in state.artifacts],
+            tool_calls=[c.model_dump(mode="json") if hasattr(c, "model_dump") else dict(c) for c in state.tool_calls],
+            validation=[v.model_dump(mode="json") if hasattr(v, "model_dump") else dict(v) for v in state.validation_results],
+            error=state.error,
+            raw_state=state,
+        )
+
+    def analyze_sync(
+        self,
+        dataset: str | Path | Dataset,
+        task: str,
+        *,
+        run_id: str | None = None,
+    ) -> Analysis:
+        """Run an analysis (sync wrapper).
+
+        Description:
+            Sync wrapper around :meth:`analyze` via ``asyncio.run``.
+            Suitable for scripts/CLI; in Jupyter with a running loop, use ``await analyze``.
+
+        Parameters:
+            Same as :meth:`analyze`.
+
+        Return Value:
+            ``Analysis``.
+
+        Errors:
+            Same as :meth:`analyze`; may raise ``RuntimeError`` if called inside
+            a running event loop (use ``await analyze`` instead).
+
+        Example:
+            >>> from data_science_agent import Agent
+            >>> Agent().analyze_sync("sales.csv", "Analyze revenue")  # doctest: +SKIP
+
+        Version:
+            4.0.0 Stable
+        """
+        return asyncio.run(self.analyze(dataset, task, run_id=run_id))
+
+    def profile(self, dataset: str | Path | Dataset) -> dict[str, Any]:
+        """Profile a dataset.
+
+        Description:
+            Load a dataset via ``dsa_datasets.loader`` and return row count
+            and columns (Polars-aware). Stable.
+
+        Parameters:
+            dataset: Path or ``Dataset`` handle.
+
+        Return Value:
+            ``{"rows": int, "columns": list[str], "path": str}``.
+
+        Errors:
+            ``FileNotFoundError`` if missing; ``ValueError`` for unsupported format.
+
+        Example:
+            >>> Agent().profile("benchmarks/v2/datasets/sales.csv")  # doctest: +SKIP
+            {'rows': 500, ...}
+
+        Version:
+            4.0.0 Stable
+        """
+        from dsa_datasets.loader import load_dataframe
+        from dsa_datasets.validate import detect_format
+
+        p = Path(dataset.path) if isinstance(dataset, Dataset) else Path(str(dataset))
+        fmt = detect_format(p.name)
+        df = load_dataframe(p, fmt)
+        return {"rows": df.height if hasattr(df, "height") else len(df), "columns": list(df.columns), "path": str(p)}
+
+    @property
+    def version(self) -> str:
+        """SDK version (mirrors ``pyproject.toml``).
+
+        Return Value:
+            ``"4.0.0"`` string.
+
+        Version:
+            4.0.0 Stable
+        """
+        return self._version
+
+
+@dataclass
+class BenchmarkResult:
+    """Result of ``Benchmark.run``.
+
+    Description:
+        Aggregate benchmark outcome over catalog tasks. Stable.
+
+    Parameters:
+        n_tasks: Number of tasks executed.
+        aggregate: Aggregate metrics (task_success_rate etc.).
+        results: Per-task result dicts.
+
+    Return Value:
+        ``BenchmarkResult``.
+
+    Errors:
+        ``Benchmark.run`` may raise ``FileNotFoundError`` for missing catalog.
+
+    Example:
+        >>> from data_science_agent import Benchmark
+        >>> r = Benchmark().run(limit=1)  # doctest: +SKIP
+        >>> r.n_tasks
+        1
+
+    Version:
+        4.0.0 Stable
+    """
+
+    n_tasks: int
+    aggregate: dict[str, Any] = field(default_factory=dict)
+    results: list[dict[str, Any]] = field(default_factory=list)
+
+
+class Benchmark:
+    """Benchmark facade (V4 §16) over evaluation framework.
+
+    Description:
+        Runs ``dsa_evaluation.runner.run_benchmark`` and returns typed result.
+        Stable since 4.0.0; catalog default is ``benchmarks/ds-agent-benchmark``.
+
+    Parameters:
+        None on construction.
+
+    Return Value:
+        Constructed ``Benchmark``.
+
+    Errors:
+        ``run`` may raise ``FileNotFoundError`` if catalog/datasets missing.
+
+    Example:
+        >>> from data_science_agent import Benchmark
+        >>> Benchmark().run(limit=1)  # doctest: +SKIP
+
+    Version:
+        4.0.0 Stable
+    """
+
+    def run(
+        self,
+        catalog: str | Path = "benchmarks/ds-agent-benchmark/catalog.json",
+        datasets: str | Path = "benchmarks/ds-agent-benchmark/datasets",
+        out: str | Path = "benchmarks/ds-agent-benchmark/results",
+        limit: int | None = None,
+    ) -> BenchmarkResult:
+        """Run benchmark.
+
+        Description:
+            Execute benchmark catalog over dataset dir.
+
+        Parameters:
+            catalog: Path to ``catalog.json``.
+            datasets: Directory of datasets.
+            out: Output dir for ``results.json`` etc.
+            limit: Optional limit for smoke runs.
+
+        Return Value:
+            ``BenchmarkResult`` with ``n_tasks`` and ``aggregate``.
+
+        Errors:
+            ``FileNotFoundError`` for missing paths.
+
+        Example:
+            >>> Benchmark().run(limit=1)  # doctest: +SKIP
+
+        Version:
+            4.0.0 Stable
+        """
+        from dsa_evaluation.runner import run_benchmark
+
+        payload = run_benchmark(Path(catalog), Path(datasets), Path(out), limit=limit)
+        return BenchmarkResult(
+            n_tasks=payload.get("n_tasks", 0),
+            aggregate=payload.get("aggregate", {}),
+            results=payload.get("results", []),
+        )
+
+
+@dataclass
+class ReproductionResult:
+    """Result of ``Reproduction.run``.
+
+    Description:
+        6-dim reproducibility score (overall/execution/trajectory/by_level). Stable.
+
+    Parameters:
+        overall: Overall score 0–1.
+        execution: Execution match rate.
+        trajectory: Trajectory match rate.
+        by_level: Scores by level L0–L5.
+        out_dir: Output directory.
+
+    Return Value:
+        ``ReproductionResult``.
+
+    Errors:
+        ``run`` may raise on missing catalog; fallback writes ``out_dir`` alone.
+
+    Example:
+        >>> ReproductionResult(overall=0.9)
+        ReproductionResult(overall=0.9, ...)
+
+    Version:
+        4.0.0 Stable
+    """
+
+    overall: float = 0.0
+    execution: float = 0.0
+    trajectory: float = 0.0
+    by_level: dict[str, float] = field(default_factory=dict)
+    out_dir: str = ""
+
+
+class Reproduction:
+    """Reproduction facade (V4 §16) over reproducibility harness.
+
+    Description:
+        Runs fresh-twice reproduction harness and reads ``comparison.json``.
+        Stable since 4.0.0.
+
+    Parameters:
+        None on construction.
+
+    Return Value:
+        ``Reproduction``.
+
+    Errors:
+        ``run`` may raise ``FileNotFoundError``; returns partial ``ReproductionResult`` on failure.
+
+    Example:
+        >>> from data_science_agent import Reproduction
+        >>> Reproduction().run()  # doctest: +SKIP
+
+    Version:
+        4.0.0 Stable
+    """
+
+    def run(
+        self,
+        catalog: str | Path = "benchmarks/v2/catalog.json",
+        datasets: str | Path = "benchmarks/v2/datasets",
+        out: str | Path = "reproduction/v2",
+    ) -> ReproductionResult:
+        """Run reproduction harness.
+
+        Description:
+            Execute ``_reproduce_benchmark`` (or fallback ``run_benchmark``) and parse
+            ``comparison.json`` for 6-dim scores.
+
+        Parameters:
+            catalog: Catalog json.
+            datasets: Datasets dir.
+            out: Output dir for ``manifest.json/comparison.json``.
+
+        Return Value:
+            ``ReproductionResult``.
+
+        Errors:
+            Never raises for missing ``comparison.json`` (returns empty scores).
+
+        Example:
+            >>> Reproduction().run()  # doctest: +SKIP
+
+        Version:
+            4.0.0 Stable
+        """
+        from dsa_evaluation.cli import _reproduce_benchmark
+
+        # _reproduce_benchmark is internal; fallback to runner if missing
+        try:
+            _reproduce_benchmark(Path(catalog), Path(datasets), Path(out))
+        except Exception:
+            from dsa_evaluation.runner import run_benchmark as _rb
+
+            _rb(Path(catalog), Path(datasets), Path(out))
+        # Try to read comparison
+        try:
+            import json
+
+            comp = json.loads((Path(out) / "comparison.json").read_text(encoding="utf-8"))
+            rs = comp.get("reproduction_score", {})
+            return ReproductionResult(
+                overall=float(rs.get("overall", 0)),
+                execution=float(rs.get("execution", 0)),
+                trajectory=float(rs.get("trajectory", 0)),
+                by_level=rs.get("by_level", {}),
+                out_dir=str(out),
+            )
+        except Exception:
+            return ReproductionResult(out_dir=str(out))
+
+
+@dataclass
+class Report:
+    """Report handle.
+
+    Description:
+        Pointer to a generated report (markdown + optional path). Stable.
+
+    Parameters:
+        run_id: Associated run id.
+        markdown: Markdown content if in-memory.
+        path: Filesystem path if persisted.
+
+    Return Value:
+        ``Report``.
+
+    Errors:
+        None.
+
+    Example:
+        >>> Report(run_id="run-1", markdown="# Report")
+
+    Version:
+        4.0.0 Stable
+    """
+
+    run_id: str
+    markdown: str | None = None
+    path: str | None = None

jack_data_science_agent-4.1.0.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.5
+Name: jack-data-science-agent
+Version: 4.1.0
+Summary: An Evidence-Grounded Autonomous Data Science System — from natural language to reproducible analysis
+Project-URL: Homepage, https://github.com/Jackxiaozhiren/data-science-agent
+Project-URL: Repository, https://github.com/Jackxiaozhiren/data-science-agent
+Project-URL: Documentation, https://github.com/Jackxiaozhiren/data-science-agent/blob/main/docs/getting-started.md
+Project-URL: Changelog, https://github.com/Jackxiaozhiren/data-science-agent/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Jackxiaozhiren/data-science-agent/issues
+Author-email: Data Science Agent Contributors <jackxiaozhiren@users.noreply.github.com>
+Maintainer-email: Data Science Agent Maintainers <jackxiaozhiren@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,benchmark,data-science,duckdb,evidence,llm,mcp,polars,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: dsa-agent
+Requires-Dist: dsa-api
+Requires-Dist: dsa-datasets
+Requires-Dist: dsa-evaluation
+Requires-Dist: dsa-evidence
+Requires-Dist: dsa-execution
+Requires-Dist: dsa-llm
+Requires-Dist: dsa-mcp
+Requires-Dist: dsa-ml
+Requires-Dist: dsa-plugins
+Requires-Dist: dsa-reports
+Requires-Dist: dsa-statistics
+Requires-Dist: dsa-tools
+Requires-Dist: dsa-visualization
+Requires-Dist: duckdb>=1.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: greenlet>=3.5.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langgraph>=0.2
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.26
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.12
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev-jupyter
+Requires-Dist: dsa-jupyter; extra == 'dev-jupyter'
+Requires-Dist: ipykernel>=6.0; extra == 'dev-jupyter'
+Requires-Dist: ipython>=8.0; extra == 'dev-jupyter'
+Requires-Dist: jupyterlab>=4.0; extra == 'dev-jupyter'
+Requires-Dist: nest-asyncio>=1.5; extra == 'dev-jupyter'
+Provides-Extra: jupyter
+Requires-Dist: dsa-jupyter; extra == 'jupyter'
+Requires-Dist: ipykernel>=6.0; extra == 'jupyter'
+Requires-Dist: ipython>=8.0; extra == 'jupyter'
+Requires-Dist: nest-asyncio>=1.5; extra == 'jupyter'
+Provides-Extra: time-series
+Requires-Dist: statsmodels>=0.14; extra == 'time-series'
+Description-Content-Type: text/markdown
+
+# Data Science Agent — v4.1.0
+
+> **An Evidence-Grounded Autonomous Data Science System.**
+> Turn natural-language questions into reproducible statistical analysis, machine learning experiments, visualizations, and research reports.
+
+**What is it?** Autonomous data science agent with grounded evidence chains (Insight → Evidence → ToolCall → Dataset hash).
+**Why does it exist?** Turn NL questions into verifiable analyses rather than free-text LLM summaries.
+**Why is it different?** Evidence-grounded · Reproducible bundles (`reproduce.sh` + `analysis.ipynb`) · Formal evaluation (10 dims × 6 levels, statistical rigor S01–S10) · Local-first (no cloud required, `Cloud $0`) · MCP 2026-07-28 stateless.
+**How do I run it?** `uv sync --dev` → `uv run dsa demo` (one-command, see Quick Start).
+**How is it evaluated?** Benchmark v2: `30 datasets / 100 tasks / 11 categories, seed 42` via `dsa --catalog benchmarks/v2/catalog.json ...` — metrics: task success, statistical/tool/evidence, evaluator_v2.
+**How is it reproducible?** `dsa reproduce` ↔ `reproduction/{manifest,environment,results,comparison,logs}` + `ReproductionScore` (6-dim, L0–L5) — see `docs/v3/`.
+
+V2 adds: Evaluation Framework · Scientific Benchmark v2 (30/100/11) · Reliability & Reproducibility · Failure Taxonomy F01–F15 · Observability · MCP 2026-07-28 Stateless · Security Hardening · Research Package (RQs + ablation A–F). V3 adds: scientific audit (0.3.0, §13–17 versioned), independent reproduction, statistical upgrade (evaluator_v2), cross-model frontier, human evaluation (11/100, Kappa/Alpha), external validation (`dsa demo`). V4 adds: **Stable** — SDK (`from data_science_agent import Agent`), product CLI (`dsa doctor/init/analyze/profile/benchmark`), plugin architecture, MCP Tools (18 stateless `+analyze` §36, 12/12 PASS), MCP Resources (5 schemes §37), Jupyter (`%dsa` + rich) · **Experimental** — Time Series Plugin (`dsa-time-series 1.0.0` → Stable after W3), MCP App (`/mcp-app` Dataset→Question→Analysis→Evidence→Viz→Report §36, explicit handles §38), VS Code (`Dataset Explorer / Ask DSA`) — see `docs/v4_1/RELEASE_MATRIX.md` (§58) + `docs/v4_1/MCP_COMPATIBILITY.md` (§40).
+
+**Quantitative claims (see §45):** Any number like `50/50 @1.0`, `100/100 @1.0`, `81% coverage`, `13 routes` must cite `Benchmark Version + Commit + Report` (e.g. `benchmarks/v2 0.3.0 + commit 1b6c3bf + docs/v3/V2_FINAL_BASELINE.md` or `benchmarks/baseline`). Avoid `State-of-the-art / Best / Enterprise-grade / Production-ready` without evidence.
+
+## Documentation
+
+Docs: [Getting Started](./docs/getting-started.md) · [Agent](./docs/agent.md) · [Tools](./docs/tools.md) · [Evidence](./docs/evidence.md) · [API](./docs/api.md) · [MCP](./docs/MCP_DESIGN.md) · [Frontend IA](./docs/FRONTEND_IA.md) · [Research](./docs/research.md) · [Changelog](./CHANGELOG.md) · [Roadmap](./ROADMAP.md) · [Citation](./CITATION.cff)
+V2: [Baseline Report](./docs/v2/Baseline%20Report.md) · [Evaluation](./docs/v2/evaluation.md) · [MCP 2026-07-28](./docs/v2/MCP_2026_Audit.md) · [Security (W9)](./docs/v2/security.md) · [Benchmark v2](./benchmarks/v2/README.md) · Benchmark baseline: [benchmarks/baseline](./benchmarks/baseline/README.md)
+V3: [V2 Baseline Freeze](./docs/v3/V2_FINAL_BASELINE.md) · [Benchmark Audit](./docs/v3/BENCHMARK_AUDIT.md) · [Reproduction](./docs/v3/REPRODUCTION.md) · [Statistical Eval](./docs/v3/STATISTICAL_EVALUATION.md) · [Reliability](./docs/v3/RELIABILITY.md) · [Cross-Model](./docs/v3/CROSS_MODEL.md) · [Human Eval](./docs/v3/HUMAN_EVALUATION_GUIDE.md) · [External Validation](./docs/v3/EXTERNAL_VALIDATION.md) — `human-eval/` samples + `demo/` one-command
+MkDocs: `uv run mkdocs serve` / `uv run mkdocs build` (see [mkdocs.yml](./mkdocs.yml)) — Architecture Freeze at [ARCHITECTURE_FREEZE_V0.1.md](./ARCHITECTURE_FREEZE_V0.1.md)
+
+## Stack
+
+Next.js 15 + TypeScript + Tailwind + shadcn/ui · FastAPI + Pydantic v2 + SQLAlchemy · LangGraph · DuckDB + Polars + PyArrow · SQLite · LLM Abstraction (OpenAI/Anthropic/Google/OpenRouter/Ollama) · Scikit-learn + SciPy + Matplotlib
+
+## Quick Start
+
+```bash
+# Python
+uv sync --dev
+uv run pytest -q          # ~86+ tests
+uv run ruff check .
+uv run mypy packages apps/api --ignore-missing-imports  # 81 source files clean
+
+# API (port 8000) — local-first, no cloud required
+uv run uvicorn dsa_api.main:app --reload --port 8000 --app-dir apps/api/src
+
+# Web (port 3000)
+cd apps/web && npm install --legacy-peer-deps && npm run dev
+# Build — V2: 13 routes (/benchmarks /evaluations /runs /runs/[id] /runs/[id]/replay /failures /research /mcp)
+npm run build --workspace=dsa-web  # 13 routes green
+
+# Benchmark v1 (20 datasets / 50 tasks) — frozen baseline: benchmarks/baseline — 50/50 @1.0
+# Benchmark v2 (30 datasets / 100 tasks) — benchmarks/v2 (Evaluation Framework + Evidence Validation)
+uv run dsa --help
+uv run dsa --limit 3
+uv run dsa --limit 50
+uv run dsa --catalog benchmarks/v2/catalog.json --datasets benchmarks/v2/datasets --limit 50 --out /tmp/v2-bench
+```
+
+## Demo (One-Command Smoke)
+
+```bash
+# Start API
+uv run uvicorn dsa_api.main:app --host 127.0.0.1 --port 8000 --app-dir apps/api/src &
+
+# Upload sales.csv (note: explicit MIME needed with curl)
+curl -F "file=@examples/datasets/sales.csv;type=text/csv" http://127.0.0.1:8000/api/v1/datasets/
+# -> {"id": "<dataset_id>", "rows": 500, "cols": 6, ...}
+
+# Run analysis (numeric correlation + evidence)
+curl -X POST http://127.0.0.1:8000/api/v1/analysis/ \
+  -H 'Content-Type: application/json' \
+  -d '{"dataset_id": "<dataset_id>", "user_query": "Analyze correlation between price and revenue"}'
+# -> {"id": "run-...", "status": "COMPLETED", "state": {"evidence": [...], "report_markdown": "..."}}
+
+# Check report and SSE trace
+curl http://127.0.0.1:8000/api/v1/analysis/<run_id>/report?format=markdown
+curl -H "Accept: text/event-stream" http://127.0.0.1:8000/api/v1/analysis/<run_id>/events
+
+# Or via frontend: http://localhost:3000/datasets -> upload -> Analyze -> trace
+```
+
+## API
+
+```
+POST /api/v1/datasets/              upload (multipart, 100MB, MIME sniff, traversal block)
+GET  /api/v1/datasets/{id}          profile + metadata
+POST /api/v1/analysis/              {dataset_id, user_query} -> run_id (Agent graph)
+GET  /api/v1/analysis/{id}          AnalysisState (polling)
+GET  /api/v1/analysis/{id}/events   SSE: agent/tool/validation/report/completed (JSON fallback via Accept)
+GET  /api/v1/analysis/{id}/progress progress_pct + counts
+GET  /api/v1/analysis/{id}/report   ?format=json|markdown
+GET  /api/v1/analysis/{id}/artifacts artifacts + tool_calls + progress
+GET  /api/v1/analysis/{id}/evidence/{evidence_id}  evidence → tool_call → insights → dataset trace
+POST /api/v1/analysis/{id}/approve  HUMAN_REVIEW approval (HITL)
+GET  /health  GET /ready  GET /version  GET /
+
+MCP (adapter over Tool Layer, stateless 2026-07-28):
+  GET  /mcp/tools  GET /mcp/resources  POST /mcp/call  POST /mcp (JSON-RPC: initialize/tools/list/tools/call/resources/list/resources/read)
+  Tools: 18 — profile_dataset, inspect_dataset, query_dataset, run_sql, run_python,
+         run_statistical_test, correlation_analysis, train_model, evaluate_model,
+         create_visualization, get_evidence, generate_report, save_artifact,
+         forecast, assumption_check, feature_importance, causal_check, analyze — see docs/MCP_DESIGN.md
+  Resources: 5 — dataset://, evidence://, report://, artifact://, analysis:// (§37, explicit handles §38)
+  App: /mcp-app/ — Dataset→Question→Analysis→Evidence→Viz→Report (§36) — see docs/v4_1/MCP_COMPATIBILITY.md
+```
+
+## Frontend
+
+```
+ /              Dashboard (recent analyses)
+ /datasets      Upload + list (drag-drop, 100MB guard)
+ /datasets/[id] Profile (schema, missing, duplicates, cardinality)
+ /analysis      Workspace (select dataset + natural language task)
+ /analysis/[runId]  Trace (plan/tool calls/evidence/insights/validation/artifacts/report + evidence graph)
+ /reports       Reports index
+```
+
+## Evidence & Reproducibility
+
+Every important claim traces to executable computation:
+
+```
+Insight → Evidence → ToolCall → Dataset (hash)
+```
+
+Artifacts under `artifacts/reports/<runId>/`: `report.md` (with `![chart]` embeds), `experiment.json`, `reproduce.sh`, `analysis.ipynb` (executable cells: profile + per-tool + `run_analysis`), `evidence_graph.json`.
+`uv run mkdocs serve` / `build --strict` · health: `GET /health → {status, details:{db,duckdb,polars,llm:{active,status}}, version}` + `GET /ready`.
+
+## Benchmark
+
+```
+benchmarks/ds-agent-benchmark/
+  datasets/   20 synthetic CSVs (seed 42, 8,770 rows)
+  catalog.json  50 tasks (EDA 8 / SQL 7 / Statistics 8 / Regression 6 / Classification 6 / Time Series 5 / Visualization 5 / Data Quality 5)
+  results/    (generated via dsa benchmark)
+```
+
+```bash
+uv run dsa --limit 3 --out /tmp/bench
+cat benchmarks/ds-agent-benchmark/catalog.json | jq '.tasks | length'  # 50
+```
+
+Metrics: Task Success Rate, Statistical Accuracy, SQL Accuracy, Code Execution Success, Evidence Coverage, Unsupported Claim Rate, Mean Latency, By-Category breakdown.
+
+## Security Boundary
+
+File (MIME sniff + archive bomb guard), SQL (read-only allowlist + row limit), Python (AST allowlist + _safe_import, introspection block), Prompt Injection (dataset UNTRUSTED DATA, detection), Output (unsupported causal claim rewrite), Resource limits (tool call budget), HITL approval.
+
+## Project Structure
+
+```
+data-science-agent/ (monorepo)
+  apps/api   FastAPI
+  apps/web   Next.js 15
+  packages/agent, tools, execution, statistics, ml, visualization, evidence, reports, datasets, llm, mcp, evaluation
+  benchmarks/ds-agent-benchmark
+  tests/unit, integration, security
+  docs/
+```
+
+## Development Roadmap
+
+Phase 0 Architecture Freeze ✓  Phase 1 Scaffold ✓  Phase 2 Data Layer ✓  Phase 3 Tool Layer ✓  Phase 4 Agent Graph ✓  Phase 5 Evidence ✓  Phase 6 API ✓  Phase 7 Frontend ✓  Phase 8 Security ✓  Phase 9 Benchmark ✓  Phase 10 MCP ✓  Phase 11 Docs ✓ — see `ROADMAP.md` for V3.0 W1–W12.
+V2.0 Research Grade ✓ `v2.0.0` (Evaluation 10×6 · Benchmark v2 30/100/11 · Reliability L0–L5/F01–F15 · MCP 2026-07-28 · Security 23) — `docs/v3/V2_FINAL_BASELINE.md`.
+V3.0 Release ✓ `v3.0.0` (12 workstreams, `docs/v3/V2_FINAL_BASELINE.md` + `research/V3_RESEARCH_REPORT.md`).
+V4.0 Ecosystem ✓ `v4.0.0` (SDK + CLI + Plugins + MCP Apps + Jupyter/VS Code + Community).
+
+## Testing
+
+```bash
+uv run pytest -q           # 155 tests (unit + integration + security + evals)
+uv run pytest --cov --cov-report=term-missing  # 81% cov (4597 stmts)
+uv run mypy packages apps/api --ignore-missing-imports  # strict, 92 source files clean
+uv run ruff check packages apps/api tests  # scoped per-file ignores
+uv run dsa --limit 50      # 50/50 @1.0 (benchmarks/ds-agent-benchmark, 8 cats)
+uv run dsa --catalog benchmarks/v2/catalog.json --datasets benchmarks/v2/datasets --limit 100  # 100/100 @1.0 (11 cats)
+uv run dsa demo            # one-command: demo dataset → evidence → report (§40/47)
+uv run dsa external-validation  # install + demo metrics (§42)
+docker compose config && npm --prefix apps/web run build  # compose healthcheck + 13 routes
+```
+
+## Docker
+
+```bash
+docker compose up  # api :8000, web :3000
+```
+
+## Contributing / Security
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) · [LICENSE](./LICENSE) (MIT)

jack_data_science_agent-4.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+data_science_agent/__init__.py,sha256=j4lit9XRkI7dGUpxNSIwM4BXQ5eYW3Y6RfKfLKmqi5c,456
+data_science_agent/sdk.py,sha256=sPcWCbOobw3ysr1ySFax5fYavU5r32BcRXxio1pHIpY,19617
+jack_data_science_agent-4.1.0.dist-info/METADATA,sha256=wFLeaDIgfeK7vz3tDuSbbHudDWyPm9QzPvbUI1JpeZU,14579
+jack_data_science_agent-4.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+jack_data_science_agent-4.1.0.dist-info/licenses/LICENSE,sha256=gkgxTdPCq7g0o3xaYAJAeNtHdPbeg_Rv0unarH36GXA,1088
+jack_data_science_agent-4.1.0.dist-info/RECORD,,

jack_data_science_agent-4.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jack_data_science_agent-4.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Data Science Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.