spec-agents-statistics 0.2.1__tar.gz

spec_agents_statistics-0.2.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dags/
+*.egg-info/
+examples/output/
+build/
+.coverage
+coverage.xml

spec_agents_statistics-0.2.1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.2.1](https://github.com/marcionicolau/spec-agents/compare/statistics-v0.2.0...statistics-v0.2.1) (2026-10-02)
+
+
+### Bug Fixes
+
+* document the spec-agents-* distribution names in the package READMEs ([#96](https://github.com/marcionicolau/spec-agents/issues/96)) ([fffad88](https://github.com/marcionicolau/spec-agents/commit/fffad88e5c8405bb01c7d9dddf66b7cf52a13e28)), closes [#76](https://github.com/marcionicolau/spec-agents/issues/76)
+
+## [0.2.0](https://github.com/marcionicolau/spec-agents/compare/statistics-v0.1.0...statistics-v0.2.0) (2026-10-02)
+
+
+### Features
+
+* **agent-fabric:** core/pack API level contract ([#75](https://github.com/marcionicolau/spec-agents/issues/75)) ([d880a74](https://github.com/marcionicolau/spec-agents/commit/d880a744481b888e1e435a1c0d482e44fa942e03)), closes [#20](https://github.com/marcionicolau/spec-agents/issues/20)
+* **agent-fabric:** define the public API surface with __all__, fix __version__ ([#57](https://github.com/marcionicolau/spec-agents/issues/57)) ([c9ab564](https://github.com/marcionicolau/spec-agents/commit/c9ab56432fb2e95c5f1a1ebd9428a23c42b9d89f)), closes [#56](https://github.com/marcionicolau/spec-agents/issues/56)
+
+## [0.1.0](https://github.com/marcionicolau/spec-agents/compare/statistics-v0.0.1...statistics-v0.1.0) (2026-10-01)
+
+
+### Features
+
+* **agent-fabric:** enforce architecture boundaries and type-check the core; fix live view crash ([#38](https://github.com/marcionicolau/spec-agents/issues/38)) ([45b277f](https://github.com/marcionicolau/spec-agents/commit/45b277f586b14bf966d13f3eaacb66df52f5649b))
+
+
+### Bug Fixes
+
+* **statistics:** warn on perfect collinearity with inf VIF; ci: require lowest-versions job ([#35](https://github.com/marcionicolau/spec-agents/issues/35)) ([e1502a1](https://github.com/marcionicolau/spec-agents/commit/e1502a1a7d0cfb65dd65e6087843ae6bddc4a378))

spec_agents_statistics-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcio Nicolau
+
+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.

spec_agents_statistics-0.2.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: spec-agents-statistics
+Version: 0.2.1
+Summary: Statistics domain pack for agent-fabric: summary, linear_model, anova, time_series, pca, clustering
+Project-URL: Homepage, https://github.com/marcionicolau/spec-agents
+Project-URL: Repository, https://github.com/marcionicolau/spec-agents
+Project-URL: Issues, https://github.com/marcionicolau/spec-agents/issues
+Project-URL: Changelog, https://github.com/marcionicolau/spec-agents/blob/main/packages/statistics/CHANGELOG.md
+Project-URL: Documentation, https://github.com/marcionicolau/spec-agents/tree/main/docs
+Author: Marcio Nicolau
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,pandas,statistics
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pandas>=2.1
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.12
+Requires-Dist: spec-agents-core<1,>=0.0.1
+Requires-Dist: statsmodels>=0.14.2
+Description-Content-Type: text/markdown
+
+# spec-agents-statistics (`stat_fabric`)
+
+Statistics domain pack for [agent-fabric](../agent-fabric/README.md): deterministic components `summary`, `linear_model`, `anova`,
+`time_series`, `pca`, `clustering` and the pipelines `exploratory_analysis`, `experiment_analysis`, `full_study`. Formulas are built from
+validated column names; no model-written code is executed. Also provides `StatsRulePlanner` (planner backend `stats_rules`, no LLM).
+
+> **Status:** pre-release. Until the first PyPI release, install a wheel from the
+> [GitHub Releases](https://github.com/marcionicolau/spec-agents/releases) or use `uv sync --all-packages` in a checkout;
+> the `pip install` lines below are the PyPI names.
+
+## Names
+
+| | |
+| --- | --- |
+| PyPI distribution | `spec-agents-statistics` |
+| Import name | `stat_fabric` |
+| Directory in the monorepo | `packages/statistics` |
+| Release tag / PR scope | `statistics-vX.Y.Z` / `statistics` |
+
+The distribution is named `spec-agents-statistics` because the shorter names are taken on PyPI; the import name and the entry point do not change.
+
+## Install
+```bash
+pip install spec-agents-statistics   # pulls spec-agents-core, pandas, scipy, statsmodels, scikit-learn
+```
+The pack registers as the `statistics` domain via the `agent_fabric.domains` entry point:
+```python
+from agent_fabric import build_registry
+
+registry = build_registry(discover=True)  # or build_registry([stat_fabric.domain.register])
+```
+Each component's contract and guidance is a `SKILL.md` under `stat_fabric/skills/`.

spec_agents_statistics-0.2.1/README.md

@@ -0,0 +1,32 @@
+# spec-agents-statistics (`stat_fabric`)
+
+Statistics domain pack for [agent-fabric](../agent-fabric/README.md): deterministic components `summary`, `linear_model`, `anova`,
+`time_series`, `pca`, `clustering` and the pipelines `exploratory_analysis`, `experiment_analysis`, `full_study`. Formulas are built from
+validated column names; no model-written code is executed. Also provides `StatsRulePlanner` (planner backend `stats_rules`, no LLM).
+
+> **Status:** pre-release. Until the first PyPI release, install a wheel from the
+> [GitHub Releases](https://github.com/marcionicolau/spec-agents/releases) or use `uv sync --all-packages` in a checkout;
+> the `pip install` lines below are the PyPI names.
+
+## Names
+
+| | |
+| --- | --- |
+| PyPI distribution | `spec-agents-statistics` |
+| Import name | `stat_fabric` |
+| Directory in the monorepo | `packages/statistics` |
+| Release tag / PR scope | `statistics-vX.Y.Z` / `statistics` |
+
+The distribution is named `spec-agents-statistics` because the shorter names are taken on PyPI; the import name and the entry point do not change.
+
+## Install
+```bash
+pip install spec-agents-statistics   # pulls spec-agents-core, pandas, scipy, statsmodels, scikit-learn
+```
+The pack registers as the `statistics` domain via the `agent_fabric.domains` entry point:
+```python
+from agent_fabric import build_registry
+
+registry = build_registry(discover=True)  # or build_registry([stat_fabric.domain.register])
+```
+Each component's contract and guidance is a `SKILL.md` under `stat_fabric/skills/`.

spec_agents_statistics-0.2.1/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "spec-agents-statistics"
+dynamic = ["version"]
+description = "Statistics domain pack for agent-fabric: summary, linear_model, anova, time_series, pca, clustering"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "Marcio Nicolau" }]
+keywords = ["statistics", "agents", "pandas"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "spec-agents-core>=0.0.1,<1",
+  "pandas>=2.1",
+  "scipy>=1.12",
+  "statsmodels>=0.14.2",
+  "scikit-learn>=1.4",
+]
+
+[project.entry-points."agent_fabric.domains"]
+statistics = "stat_fabric.domain:register"
+
+[project.urls]
+Homepage = "https://github.com/marcionicolau/spec-agents"
+Repository = "https://github.com/marcionicolau/spec-agents"
+Issues = "https://github.com/marcionicolau/spec-agents/issues"
+Changelog = "https://github.com/marcionicolau/spec-agents/blob/main/packages/statistics/CHANGELOG.md"
+Documentation = "https://github.com/marcionicolau/spec-agents/tree/main/docs"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.14"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+spec-agents-core = { workspace = true }
+
+# version = latest "statistics-vX.Y.Z" git tag (other packages' tags are ignored); untagged commits get X.Y.(Z+1).devN+<sha>
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stat_fabric"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+pattern-prefix = "statistics-"
+fallback-version = "0.0.0"

spec_agents_statistics-0.2.1/src/stat_fabric/__init__.py

@@ -0,0 +1,16 @@
+"""Statistics domain pack for agent_fabric."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["register"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy export: ``register`` (the ``agent_fabric.domains`` entry point) without importing the pack's heavy dependencies."""
+    if name == "register":
+        from .domain import register
+
+        return register
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

spec_agents_statistics-0.2.1/src/stat_fabric/app.py

@@ -0,0 +1,86 @@
+"""Facade for the statistics domain on top of the generic agent fabric.
+
+fabric = StatisticalAnalysisFabric.from_config("config", domains=[text_pack.register])  # AGENT.md tree
+report = fabric.analyze(df, "Which treatments raise yield?", session_id="trial-2026")
+print(render_markdown(report))
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from agent_fabric import build_registry
+from agent_fabric.agents import AgentFabric, AgentRunReport, AgentsConfig, AgentSpec
+from agent_fabric.llm.backends import LLMBackend
+from agent_fabric.memory import MemoryPort
+
+from .domain import register
+from .schemas import SCHEMAS
+
+DEFAULT_CONFIG = AgentsConfig(
+    root="statistician",
+    agents={
+        "statistician": AgentSpec(
+            kind="planner",
+            backend="fabric",
+            fallback="stats_rules",
+            domains=["statistics"],
+            role="Senior statistician",
+            goal="Plan and run the smallest valid statistical pipeline",
+            interpret="rules",
+            options={"repair": True},
+        ),
+    },
+)
+
+
+class StatisticalAnalysisFabric:
+    """Facade over the generic fabric for statistical analysis.
+
+    ``from_config(path, domains=...)`` loads an agent tree (default: one ``statistician`` planner with a rules fallback); ``analyze(df, question)``
+    runs it on a DataFrame and returns an `AgentRunReport`.
+    """
+
+    def __init__(
+        self,
+        config: AgentsConfig | None = None,
+        *,
+        backend: LLMBackend | None = None,
+        memory: MemoryPort | None = None,
+        registry: Any = None,
+    ) -> None:
+        self.registry = registry or build_registry([register])
+        self.agents = AgentFabric(self.registry, config or DEFAULT_CONFIG, backend=backend, memory=memory)
+        for name, model in SCHEMAS.items():
+            self.agents.register_schema(name, model)
+
+    @classmethod
+    def from_config(cls, path: str | Path, domains: Iterable[Callable] = (), **kw: Any) -> StatisticalAnalysisFabric:
+        """``path``: agents directory (fabric.md + agents/*/AGENT.md) or legacy YAML file.
+        ``domains``: extra domain packs the tree needs besides statistics."""
+        return cls(AgentsConfig.load(path), registry=build_registry([register, *domains]), **kw)
+
+    def analyze(
+        self,
+        df: pd.DataFrame,
+        objective: str,
+        *,
+        session_id: str = "default",
+        root: str | None = None,
+        extra_inputs: dict[str, Any] | None = None,
+    ) -> AgentRunReport:
+        """Run the agent tree on a DataFrame and a question; returns the `AgentRunReport`.
+
+        The frame is bound to the ``data`` input (``extra_inputs`` add more, e.g. ``notes``); ``root`` picks the root agent when the config has
+        several candidates and ``session_id`` selects the memory session.
+        """
+        return self.agents.run(objective, {"data": df, **(extra_inputs or {})}, root=root, session_id=session_id)
+
+
+__all__ = [
+    "StatisticalAnalysisFabric",
+]

spec_agents_statistics-0.2.1/src/stat_fabric/components/__init__.py

@@ -0,0 +1,6 @@
+"""Statistics components. Importing this package declares them via ``@component``."""
+
+from . import descriptive, inferential, multivariate, temporal  # noqa: F401
+from .base import TableComponent, TableResult
+
+__all__ = ["TableComponent", "TableResult"]

spec_agents_statistics-0.2.1/src/stat_fabric/components/base.py

@@ -0,0 +1,47 @@
+"""Base for statistics components: a component whose main input port is a ``dataframe``."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Any, ClassVar
+
+import pandas as pd
+from pydantic import Field
+
+from agent_fabric.component import Component, ComponentParams, ComponentResult, Num, StepContext
+from agent_fabric.errors import ErrorDetail
+
+__all__ = ["ComponentParams", "Num", "StepContext", "TableComponent", "TableResult"]
+
+
+class TableResult(ComponentResult):
+    n_used: int = Field(0, description="rows actually used after dropping missing values")
+
+
+class TableComponent[P: ComponentParams, R: TableResult](Component[P, R]):
+    data_port: ClassVar[str] = "data"
+
+    @property
+    def min_rows(self) -> int:
+        """Minimum number of rows declared by the constraints of the data port."""
+        return self.port_constraints[self.data_port].min_rows
+
+    def compute(self, inputs: dict[str, Any], params: P, ctx: StepContext) -> R:
+        """Run the component on the DataFrame bound to its data port; delegates to `compute_table`."""
+        return self.compute_table(inputs.get(self.data_port), params, ctx, inputs)
+
+    @abstractmethod
+    def compute_table(self, df: pd.DataFrame | None, params: P, ctx: StepContext, inputs: dict[str, Any]) -> R:
+        """Compute the result from the DataFrame (``None`` when the component also works without one).
+
+        Subclasses implement this; ``inputs`` holds every bound input and ``ctx.emit`` stores declared extra outputs.
+        """
+        ...
+
+    def extra_checks(self, inputs: dict[str, Any], params: P) -> list[ErrorDetail]:
+        df = inputs.get(self.data_port)
+        return self.extra_data_checks(df, params) if df is not None else []
+
+    def extra_data_checks(self, df: pd.DataFrame, params: P) -> list[ErrorDetail]:
+        """Component-specific checks on the data, run after the generic table checks; returns located errors (default: none)."""
+        return []

spec_agents_statistics-0.2.1/src/stat_fabric/components/descriptive.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import pandas as pd
+from pydantic import BaseModel, Field
+from scipy import stats
+
+from agent_fabric.registry import component
+from agent_fabric.tabular import ColumnKind, infer_kind
+
+from .base import ComponentParams, Num, StepContext, TableComponent, TableResult
+
+
+class SummaryParams(ComponentParams):
+    columns: list[str] | None = Field(None, description="columns to describe; None = all")
+    include_normality: bool = True
+    max_categories: int = Field(10, ge=1, le=50)
+
+
+class NumericSummary(BaseModel):
+    count: int
+    missing: int
+    mean: Num
+    std: Num
+    min: Num
+    q1: Num
+    median: Num
+    q3: Num
+    max: Num
+    skewness: Num
+    kurtosis: Num
+    shapiro_p: Num = None
+
+
+class CategoricalSummary(BaseModel):
+    count: int
+    missing: int
+    n_levels: int
+    top_levels: dict[str, int]
+
+
+class SummaryResult(TableResult):
+    n_rows: int
+    numeric: dict[str, NumericSummary]
+    categorical: dict[str, CategoricalSummary]
+    correlations: dict[str, dict[str, Num]] = Field(default_factory=dict)
+
+
+@component("summary")
+class Summary(TableComponent[SummaryParams, SummaryResult]):
+    Params = SummaryParams
+    Result = SummaryResult
+
+    def summarize(self, r: dict) -> tuple[str, list[str]]:
+        head = f"{r['n_rows']} rows: {len(r['numeric'])} numeric and {len(r['categorical'])} categorical variables described."
+        return head, [
+            f"{k}: mean {v['mean']:.4g}, sd {v['std']:.4g}"
+            for k, v in list(r["numeric"].items())[:5]
+            if v["mean"] is not None and v["std"] is not None
+        ]
+
+    def compute_table(self, df: pd.DataFrame, params: SummaryParams, ctx: StepContext, inputs: dict) -> SummaryResult:
+        """Describe the selected columns.
+
+        Numeric columns get count, missing values, mean, standard deviation, quartiles, skewness, kurtosis and, optionally, a Shapiro-Wilk
+        normality test (only for 3 to 5000 values). Categorical and boolean columns get the number of levels and the top levels. With two or
+        more numeric columns the Pearson correlation matrix is added. Warns about non-normal columns and columns with over 20% missing values.
+        """
+        cols = params.columns or list(df.columns)
+        numeric, categorical, warns = {}, {}, []
+        for c in cols:
+            s = df[c]
+            kind = infer_kind(s)
+            if kind == ColumnKind.NUMERIC:
+                x = s.dropna().astype(float)
+                shapiro_p = None
+                if params.include_normality and 3 <= len(x) <= 5000 and x.nunique() > 1:
+                    shapiro_p = float(stats.shapiro(x).pvalue)
+                    if shapiro_p < 0.05:
+                        warns.append(f"'{c}' departs from normality (Shapiro p={shapiro_p:.3g})")
+                numeric[c] = NumericSummary(
+                    count=len(x),
+                    missing=int(s.isna().sum()),
+                    mean=x.mean(),
+                    std=x.std(),
+                    min=x.min(),
+                    q1=x.quantile(0.25),
+                    median=x.median(),
+                    q3=x.quantile(0.75),
+                    max=x.max(),
+                    skewness=x.skew() if len(x) > 2 else None,
+                    kurtosis=x.kurt() if len(x) > 3 else None,
+                    shapiro_p=shapiro_p,
+                )
+            elif kind in (ColumnKind.CATEGORICAL, ColumnKind.BOOLEAN):
+                vc = s.astype(str).where(s.notna()).value_counts()
+                categorical[c] = CategoricalSummary(
+                    count=int(s.notna().sum()),
+                    missing=int(s.isna().sum()),
+                    n_levels=int(vc.size),
+                    top_levels={str(k): int(v) for k, v in vc.head(params.max_categories).items()},
+                )
+            if s.isna().mean() > 0.2:
+                warns.append(f"'{c}' has {s.isna().mean():.0%} missing values")
+        corr = {}
+        if len(numeric) >= 2:
+            m = df[list(numeric)].corr(method="pearson")
+            corr = {a: {b: m.loc[a, b] for b in m.columns if b != a} for a in m.index}
+            strong = {tuple(sorted((a, b))) for a in m.index for b in m.columns if a != b and abs(m.loc[a, b]) >= 0.9}
+            warns += [f"'{a}' and '{b}' are highly correlated (|r|>=0.9)" for a, b in sorted(strong)]
+        return SummaryResult(
+            n_rows=len(df), n_used=len(df), numeric=numeric, categorical=categorical, correlations=corr, warnings=warns
+        )
+
+
+__all__ = [
+    "CategoricalSummary",
+    "NumericSummary",
+    "Summary",
+    "SummaryParams",
+    "SummaryResult",
+]