nancora 0.1.0__tar.gz

nancora-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.venv*/
+venv/
+scratch/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.png
+.DS_Store
+

nancora-0.1.0/LICENSE

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

nancora-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: nancora
+Version: 0.1.0
+Summary: A Python data-science toolkit that recommends which analyses are worth attention.
+Project-URL: Homepage, https://github.com/nancora/nancora
+Author: Nancora
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-analysis,eda,recommendation,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: plotly>=5.18
+Requires-Dist: scipy>=1.10
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# Nancora
+
+Nancora is a Python data-science toolkit that **recommends which analyses are worth attention**.
+
+It does not reimplement Pandas, NumPy, SciPy, Matplotlib, or Plotly. Those libraries do the computation. Nancora profiles data, generates analysis candidates, scores them with an **explainable heuristic**, removes redundant work, and returns a machine-readable result plus an HTML report.
+
+```python
+import nancora as nc
+
+df = nc.read_csv("data.csv")
+
+# 1. Unsupervised exploration
+result = nc.explore(df)
+
+# 2. Target-aware exploration
+result = nc.explore(df, target="target_column")
+
+# Jupyter Notebook Experience: Simply evaluate `result` for clean, rich HTML rendering!
+
+# 3. Clean structured properties
+result.profile          # Dataset shape, column kinds, quality stats
+result.recommendations  # Prioritized list of top analytical recommendations
+result.insights         # Human-readable insights from key evidence
+result.visualizations   # Matplotlib figures for top recommendations
+result.decision_trace   # Complete explanation of selected & skipped analyses
+
+# 4. Useful serialization
+result.to_dict()
+result.to_json()
+result.save("report.html")
+```
+
+Nancora follows a strict philosophy: **SELECT → PRIORITIZE → EXPLAIN → VISUALIZE** (not flood the user with unnecessary charts).
+Scores are ranking heuristics (0–100), not scientific truth. Association is not causation.
+
+## Install
+
+```bash
+pip install nancora
+```
+
+For development installation:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## CLI
+
+```bash
+nancora explore data.csv --out report.html
+nancora analyze data.csv --target y --out report.html
+```
+
+## What Nancora is not
+
+No LLM chatbot, AutoML, cloud platform, plugin marketplace, or deep-learning stack. See [LIMITATIONS.md](LIMITATIONS.md) and [docs/architecture.md](docs/architecture.md).

nancora-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Nancora
+
+Nancora is a Python data-science toolkit that **recommends which analyses are worth attention**.
+
+It does not reimplement Pandas, NumPy, SciPy, Matplotlib, or Plotly. Those libraries do the computation. Nancora profiles data, generates analysis candidates, scores them with an **explainable heuristic**, removes redundant work, and returns a machine-readable result plus an HTML report.
+
+```python
+import nancora as nc
+
+df = nc.read_csv("data.csv")
+
+# 1. Unsupervised exploration
+result = nc.explore(df)
+
+# 2. Target-aware exploration
+result = nc.explore(df, target="target_column")
+
+# Jupyter Notebook Experience: Simply evaluate `result` for clean, rich HTML rendering!
+
+# 3. Clean structured properties
+result.profile          # Dataset shape, column kinds, quality stats
+result.recommendations  # Prioritized list of top analytical recommendations
+result.insights         # Human-readable insights from key evidence
+result.visualizations   # Matplotlib figures for top recommendations
+result.decision_trace   # Complete explanation of selected & skipped analyses
+
+# 4. Useful serialization
+result.to_dict()
+result.to_json()
+result.save("report.html")
+```
+
+Nancora follows a strict philosophy: **SELECT → PRIORITIZE → EXPLAIN → VISUALIZE** (not flood the user with unnecessary charts).
+Scores are ranking heuristics (0–100), not scientific truth. Association is not causation.
+
+## Install
+
+```bash
+pip install nancora
+```
+
+For development installation:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## CLI
+
+```bash
+nancora explore data.csv --out report.html
+nancora analyze data.csv --target y --out report.html
+```
+
+## What Nancora is not
+
+No LLM chatbot, AutoML, cloud platform, plugin marketplace, or deep-learning stack. See [LIMITATIONS.md](LIMITATIONS.md) and [docs/architecture.md](docs/architecture.md).

nancora-0.1.0/benchmarks/README.md

@@ -0,0 +1,10 @@
+# Benchmarks
+
+This directory is a **framework**, not a published leaderboard.
+
+- `datasets/` — tiny synthetic CSVs committed with the repo
+- `labels/` — optional human labels (`useful`, `essential`, `redundant`, `irrelevant`, `misleading`)
+- `runner.py` — runs `explore` and computes metrics **only when labels exist**
+- `metrics.py` — precision@k, essential recall, redundancy reduction, coverage, runtime, information efficiency
+
+Empty `labels` arrays mean the runner prints `no labels; skip scoring`. Do not fabricate results.

nancora-0.1.0/benchmarks/datasets/synthetic_churn.csv

@@ -0,0 +1,11 @@
+churned,tenure,contract
+True,2,Month-to-month
+True,5,Month-to-month
+True,1,Month-to-month
+True,3,Month-to-month
+False,48,Two-year
+False,60,One-year
+False,36,Two-year
+False,72,Two-year
+True,4,Month-to-month
+False,55,One-year

nancora-0.1.0/benchmarks/datasets/synthetic_linear.csv

@@ -0,0 +1,11 @@
+x,y,noise,group
+0.0,0.1,1.2,a
+1.0,2.1,-0.3,b
+2.0,4.0,0.4,a
+3.0,6.2,1.1,b
+4.0,7.9,-0.2,a
+5.0,10.1,0.8,b
+6.0,12.0,-1.0,a
+7.0,14.2,0.3,b
+8.0,15.9,0.1,a
+9.0,18.1,-0.4,b

nancora-0.1.0/benchmarks/datasets/synthetic_missing.csv

@@ -0,0 +1,11 @@
+col_a,col_b,col_c
+1.0,,3.0
+,2.0,
+3.0,,1.0
+,4.0,5.0
+5.0,,
+,6.0,7.0
+7.0,,
+,8.0,9.0
+9.0,,1.0
+,10.0,

nancora-0.1.0/benchmarks/datasets/synthetic_outliers.csv

@@ -0,0 +1,16 @@
+val,group
+1.2,A
+0.9,A
+1.1,B
+0.8,A
+1.0,B
+1.3,A
+0.7,B
+1.1,A
+0.95,B
+1.05,A
+500.0,B
+-450.0,A
+600.0,B
+-550.0,A
+700.0,B

nancora-0.1.0/benchmarks/datasets/tiny.csv

@@ -0,0 +1,7 @@
+spend,revenue,noise,region
+10,21,3,north
+11,22,8,south
+12,25,1,north
+13,27,4,east
+14,29,9,south
+15,31,2,north

nancora-0.1.0/benchmarks/labels/example.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": "1.0.0",
+  "description": "Human labels per (dataset_id, analysis_id, variables). Allowed labels: useful, essential, redundant, irrelevant, misleading. This file is empty on purpose; do not invent scores.",
+  "labels": []
+}

nancora-0.1.0/benchmarks/labels/synthetic_churn.json

@@ -0,0 +1,16 @@
+{
+  "dataset_id": "synthetic_churn",
+  "description": "Synthetic benchmark dataset with boolean churn target",
+  "labels": [
+    {
+      "analysis_id": "categorical_numeric",
+      "variables": ["churned", "tenure"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "categorical_distribution",
+      "variables": ["churned"],
+      "kind": "useful"
+    }
+  ]
+}

nancora-0.1.0/benchmarks/labels/synthetic_linear.json

@@ -0,0 +1,31 @@
+{
+  "dataset_id": "synthetic_linear",
+  "description": "Linear relationship benchmark dataset",
+  "labels": [
+    {
+      "analysis_id": "numeric_relationship",
+      "variables": ["x", "y"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "correlation_analysis",
+      "variables": ["noise", "x", "y"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "categorical_numeric",
+      "variables": ["group", "x"],
+      "kind": "useful"
+    },
+    {
+      "analysis_id": "numeric_distribution",
+      "variables": ["x"],
+      "kind": "useful"
+    },
+    {
+      "analysis_id": "missingness_analysis",
+      "variables": ["x", "y", "noise", "group"],
+      "kind": "useful"
+    }
+  ]
+}

nancora-0.1.0/benchmarks/labels/synthetic_missing.json

@@ -0,0 +1,16 @@
+{
+  "dataset_id": "synthetic_missing",
+  "description": "Synthetic benchmark dataset with high missingness",
+  "labels": [
+    {
+      "analysis_id": "missingness_analysis",
+      "variables": ["col_a", "col_b", "col_c"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "numeric_distribution",
+      "variables": ["col_a"],
+      "kind": "useful"
+    }
+  ]
+}

nancora-0.1.0/benchmarks/labels/synthetic_outliers.json

@@ -0,0 +1,21 @@
+{
+  "dataset_id": "synthetic_outliers",
+  "description": "Synthetic benchmark dataset with strong outliers",
+  "labels": [
+    {
+      "analysis_id": "outlier_analysis",
+      "variables": ["val"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "numeric_distribution",
+      "variables": ["val"],
+      "kind": "useful"
+    },
+    {
+      "analysis_id": "categorical_numeric",
+      "variables": ["group", "val"],
+      "kind": "useful"
+    }
+  ]
+}

nancora-0.1.0/benchmarks/labels/tiny.json

@@ -0,0 +1,31 @@
+{
+  "dataset_id": "tiny",
+  "description": "Tiny business benchmark dataset",
+  "labels": [
+    {
+      "analysis_id": "numeric_relationship",
+      "variables": ["revenue", "spend"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "correlation_analysis",
+      "variables": ["noise", "revenue", "spend"],
+      "kind": "essential"
+    },
+    {
+      "analysis_id": "categorical_numeric",
+      "variables": ["region", "spend"],
+      "kind": "useful"
+    },
+    {
+      "analysis_id": "numeric_distribution",
+      "variables": ["spend"],
+      "kind": "useful"
+    },
+    {
+      "analysis_id": "missingness_analysis",
+      "variables": ["spend", "revenue", "noise", "region"],
+      "kind": "useful"
+    }
+  ]
+}

nancora-0.1.0/benchmarks/metrics.py

@@ -0,0 +1,66 @@
+"""Benchmark metrics. Computed only from labels — never fabricated."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def precision_at_k(selected: list[tuple[str, tuple[str, ...]]], useful: set[tuple[str, tuple[str, ...]]], k: int) -> float | None:
+    if not useful:
+        return None
+    top = selected[:k]
+    if not top:
+        return 0.0
+    hits = sum(1 for item in top if item in useful)
+    return hits / len(top)
+
+
+def recall_essential(
+    selected: list[tuple[str, tuple[str, ...]]], essential: set[tuple[str, tuple[str, ...]]]
+) -> float | None:
+    if not essential:
+        return None
+    hits = sum(1 for item in essential if item in set(selected))
+    return hits / len(essential)
+
+
+def redundancy_reduction(n_generated_pairs: int, n_rejected_redundant: int) -> float | None:
+    if n_generated_pairs <= 0:
+        return None
+    return n_rejected_redundant / n_generated_pairs
+
+
+def coverage_of_essential(
+    selected: list[tuple[str, tuple[str, ...]]], essential: set[tuple[str, tuple[str, ...]]]
+) -> float | None:
+    return recall_essential(selected, essential)
+
+
+def information_efficiency(selected: list[tuple[str, tuple[str, ...]]]) -> float | None:
+    if not selected:
+        return None
+    units = {(aid, var) for aid, vars_ in selected for var in vars_}
+    return len(units) / len(selected)
+
+
+import json
+from pathlib import Path
+
+
+def load_labels(path: str | Path) -> list[dict]:
+    p = Path(path)
+    if not p.is_file():
+        return []
+    payload = json.loads(p.read_text(encoding="utf-8"))
+    return list(payload.get("labels") or [])
+
+
+def evaluate_labels(labels: list[dict], data_dir: str | Path) -> dict[str, Any]:
+    if not labels:
+        return {"status": "no_labels"}
+    return {"status": "ok"}
+
+
+def summarize_metrics(payload: dict[str, Any]) -> dict[str, Any]:
+    return payload
+

nancora-0.1.0/benchmarks/runner.py

@@ -0,0 +1,105 @@
+"""Run labeled recommendation checks. Skips metrics when labels are absent."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+import pandas as pd
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from nancora.engine import explore  # noqa: E402
+from nancora.types import RejectReason  # noqa: E402
+
+from benchmarks.metrics import (  # noqa: E402
+    coverage_of_essential,
+    information_efficiency,
+    precision_at_k,
+    recall_essential,
+    redundancy_reduction,
+)
+
+LABELS_DIR = Path(__file__).parent / "labels"
+DATA_DIR = Path(__file__).parent / "datasets"
+REDUNDANT_REASONS = {
+    RejectReason.EXACT_DUPLICATE.value,
+    RejectReason.SYMMETRIC_DUPLICATE.value,
+    RejectReason.SIMILAR_ANALYSIS.value,
+    RejectReason.COVERAGE_OVERLAP.value,
+    RejectReason.DOMINATED.value,
+}
+
+
+def _key(analysis_id: str, variables: list[str] | tuple[str, ...]) -> tuple[str, tuple[str, ...]]:
+    return analysis_id, tuple(sorted(variables))
+
+
+def load_labels(dataset_id: str) -> list[dict]:
+    path = LABELS_DIR / f"{dataset_id}.json"
+    if not path.exists():
+        return []
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return list(payload.get("labels") or [])
+
+
+def run_dataset(csv_path: Path) -> dict:
+    dataset_id = csv_path.stem
+    labels = load_labels(dataset_id)
+    df = pd.read_csv(csv_path)
+    started = time.perf_counter()
+    result = explore(df, max_analyses=10, rng_seed=0)
+    runtime = time.perf_counter() - started
+    selected = [_key(c.analysis_id, c.variables) for c in result.selected]
+    report = {
+        "dataset_id": dataset_id,
+        "runtime_seconds": round(runtime, 6),
+        "n_selected": len(result.selected),
+        "n_rejected": len(result.rejected),
+        "labels_present": bool(labels),
+    }
+    if not labels:
+        report["metrics"] = None
+        report["note"] = "no labels; skip scoring"
+        return report
+
+    by_kind: dict[str, set] = {k: set() for k in ("useful", "essential", "redundant", "irrelevant", "misleading")}
+    for row in labels:
+        by_kind.setdefault(row["kind"], set()).add(_key(row["analysis_id"], row["variables"]))
+
+    n_pairs = sum(1 for c in result.selected + result.rejected if len(c.variables) == 2)
+    n_red = sum(
+        1
+        for c in result.rejected
+        if c.reject_reason and c.reject_reason.value in REDUNDANT_REASONS
+    )
+    useful = by_kind["useful"] | by_kind["essential"]
+    report["metrics"] = {
+        "precision_at_5": precision_at_k(selected, useful, 5),
+        "recall_essential": recall_essential(selected, by_kind["essential"]),
+        "redundancy_reduction": redundancy_reduction(n_pairs, n_red),
+        "analytical_coverage": coverage_of_essential(selected, by_kind["essential"]),
+        "information_efficiency": information_efficiency(selected),
+        "runtime_seconds": round(runtime, 6),
+    }
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Nancora benchmark runner")
+    parser.parse_args(argv)
+    datasets = sorted(DATA_DIR.glob("*.csv"))
+    if not datasets:
+        print("no datasets found")
+        return 0
+    for path in datasets:
+        print(json.dumps(run_dataset(path), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nancora-0.1.0/docs/analysis.md

@@ -0,0 +1,16 @@
+# Analysis registry
+
+Builtin IDs:
+
+1. numeric_distribution
+2. categorical_distribution
+3. numeric_relationship
+4. categorical_numeric
+5. datetime_numeric_trend
+6. correlation_analysis
+7. outlier_analysis
+8. missingness_analysis
+9. cardinality_analysis
+10. target_aware
+
+Register more with `@nc.register_analysis` on a class implementing `propose`, `compute_evidence`, and `plot_spec`. There is no plugin marketplace in the MVP.

nancora-0.1.0/docs/api.md

@@ -0,0 +1,16 @@
+# Public API
+
+```python
+import nancora as nc
+
+nc.read_csv / read_excel / read_json / read_parquet
+nc.explore(df, max_analyses=10, rng_seed=0)
+nc.analyze(df, target=..., max_analyses=10, rng_seed=0)
+nc.register_analysis
+nc.list_analyses()
+nc.get_analysis(id)
+
+nc.data / nc.numpy / nc.stats / nc.plot / nc.analysis
+```
+
+`AnalysisResult`: `summary`, `profile`, `recommendations`, `insights`, `rejected`, `visualize`, `to_dict`, `to_json`, `save`.

nancora-0.1.0/docs/architecture.md

@@ -0,0 +1,12 @@
+# Architecture
+
+Pipeline: data → schema → profile → candidates → evidence → scoring → redundancy → ranking → recommendations → visualization → insights → report.
+
+Scientific libraries are engines, not products Nancora reimplements.
+
+- Pandas: frames and IO
+- NumPy: arrays and univariate numeric summaries
+- SciPy: named association tests
+- Matplotlib / Plotly: PlotSpec backends
+
+The recommendation engine is the product differentiator. See `src/nancora/engine/`.

nancora-0.1.0/docs/benchmarking.md

@@ -0,0 +1,7 @@
+# Benchmarking
+
+`benchmarks/runner.py` loads synthetic datasets and optional human labels.
+
+Label values: `useful`, `essential`, `redundant`, `irrelevant`, `misleading`.
+
+If a dataset has no labels, the runner **skips metrics** rather than inventing scores. Do not commit fabricated precision/recall.

nancora-0.1.0/docs/cli.md

@@ -0,0 +1,8 @@
+# CLI
+
+```bash
+nancora explore path.csv --max-analyses 10 --out report.html
+nancora analyze path.csv --target y --out report.html --json
+```
+
+Supported suffixes: `.csv`, `.json`, `.xlsx` (extra), `.parquet` (extra).

nancora-0.1.0/docs/data.md

@@ -0,0 +1,7 @@
+# Data
+
+`nc.read_csv`, `nc.read_excel`, `nc.read_json`, `nc.read_parquet` delegate to Pandas.
+
+`nc.data.infer_schema` and `nc.data.profile` produce the typed profile the engine uses.
+
+Transforms are few and engine-needed: `drop_constant`, `coerce_datetime`.

nancora-0.1.0/docs/development.md

@@ -0,0 +1,11 @@
+# Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+Python 3.10+. Src layout. CI runs Ruff and Pytest on 3.10 and 3.12.
+
+Decision tests live in `tests/regression/test_decisions.py`. Prefer obvious synthetic relationships over threshold-tuning.