linexcel 0.1.0__tar.gz

linexcel-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

linexcel-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: linexcel
+Version: 0.1.0
+Summary: Data lineage analysis for Excel workbooks — formula extraction, dependency graph, step-by-step evaluation, AI documentation
+Project-URL: Homepage, https://github.com/auspect/linexcel
+Project-URL: Repository, https://github.com/auspect/linexcel
+Author-email: Philippe Calvet <phcalvet@gmail.com>
+License-Expression: MIT
+Keywords: dependency-graph,excel,formula,lineage,openpyxl,vba
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.11
+Requires-Dist: formualizer>=0.7.1
+Requires-Dist: oletools>=0.60.2
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: ai
+Requires-Dist: google-genai>=2.10.0; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# linexcel
+
+Data lineage analysis for Excel workbooks.
+
+Extracts every formula, groups stretched patterns (R1C1 canonicalization), builds a dependency graph (cells, ranges, defined names, VBA), decomposes composite functions with step-by-step evaluation, and optionally documents calculations via AI.
+
+## Install
+
+```bash
+pip install linexcel
+# AI documentation (optional):
+pip install "linexcel[ai]"
+```
+
+## Usage
+
+```python
+from linexcel import analyze
+
+result = analyze("workbook.xlsx")
+result                    # interactive graph in marimo / Jupyter
+result.save_html("out.html")     # standalone offline HTML viewer
+result.stats              # {totalFormulas, totalNodes, ...}
+result.warnings           # list[str]
+
+# AI documentation (optional, requires google-genai):
+docs = result.document(api_key="...")        # all calculation nodes
+docs = result.document(node_ids=["A1"], api_key="...")
+result.save_html("out.html", docs=docs)      # docs embedded in HTML
+```
+
+## Features
+
+- **Formula extraction** via [formualizer](https://pypi.org/project/formualizer/) (Rust engine)
+- **Stretched pattern grouping** — 1000 identical formulas → 1 node
+- **Dependency graph** — cells, ranges, defined names, VBA procedures
+- **Step-by-step evaluation** — each operator/function evaluated individually
+- **Standalone HTML viewer** — Cytoscape.js embedded, fully offline
+- **AI documentation** — Gemini generates provable docs from deterministic lineage

linexcel-0.1.0/README.md

@@ -0,0 +1,39 @@
+# linexcel
+
+Data lineage analysis for Excel workbooks.
+
+Extracts every formula, groups stretched patterns (R1C1 canonicalization), builds a dependency graph (cells, ranges, defined names, VBA), decomposes composite functions with step-by-step evaluation, and optionally documents calculations via AI.
+
+## Install
+
+```bash
+pip install linexcel
+# AI documentation (optional):
+pip install "linexcel[ai]"
+```
+
+## Usage
+
+```python
+from linexcel import analyze
+
+result = analyze("workbook.xlsx")
+result                    # interactive graph in marimo / Jupyter
+result.save_html("out.html")     # standalone offline HTML viewer
+result.stats              # {totalFormulas, totalNodes, ...}
+result.warnings           # list[str]
+
+# AI documentation (optional, requires google-genai):
+docs = result.document(api_key="...")        # all calculation nodes
+docs = result.document(node_ids=["A1"], api_key="...")
+result.save_html("out.html", docs=docs)      # docs embedded in HTML
+```
+
+## Features
+
+- **Formula extraction** via [formualizer](https://pypi.org/project/formualizer/) (Rust engine)
+- **Stretched pattern grouping** — 1000 identical formulas → 1 node
+- **Dependency graph** — cells, ranges, defined names, VBA procedures
+- **Step-by-step evaluation** — each operator/function evaluated individually
+- **Standalone HTML viewer** — Cytoscape.js embedded, fully offline
+- **AI documentation** — Gemini generates provable docs from deterministic lineage

linexcel-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "linexcel"
+version = "0.1.0"
+description = "Data lineage analysis for Excel workbooks — formula extraction, dependency graph, step-by-step evaluation, AI documentation"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Philippe Calvet", email = "phcalvet@gmail.com" }]
+keywords = ["excel", "lineage", "formula", "dependency-graph", "vba", "openpyxl"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+]
+dependencies = [
+    "openpyxl>=3.1",
+    "formualizer>=0.7.1",
+    "oletools>=0.60.2",
+]
+
+[project.optional-dependencies]
+ai = ["google-genai>=2.10.0"]
+dev = ["pytest>=8.0", "ruff>=0.9"]
+
+[project.urls]
+Homepage = "https://github.com/auspect/linexcel"
+Repository = "https://github.com/auspect/linexcel"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/linexcel"]
+
+[tool.hatch.build.targets.sdist]
+artifacts = ["src/linexcel/assets/*.js"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/linexcel/viewer.py" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:::oletools.olevba",
+]

linexcel-0.1.0/src/linexcel/__init__.py

@@ -0,0 +1,24 @@
+"""Analyse de data lineage pour classeurs Excel.
+
+Pipeline : extraction des formules (formualizer, moteur Rust) →
+regroupement des formules étirées (canonicalisation R1C1) →
+graphe de dépendances (cellules, plages, noms définis, VBA) →
+décomposition des fonctions composées avec évaluation pas-à-pas →
+documentation automatique par IA (google-genai) fondée sur le
+lignage déterministe.
+
+Utilisable comme bibliothèque autonome (marimo, Jupyter, script), sans
+serveur FastAPI ni clé IA :
+
+    from linexcel import analyze
+    result = analyze("classeur.xlsx")   # -> LineageResult
+    result                               # graphe interactif dans marimo
+    result.save_html("lineage.html")     # visualiseur autonome
+    result.stats, result.warnings        # métadonnées
+    result.document(api_key="…")         # documentation IA (optionnelle)
+"""
+
+from linexcel.analyzer import analyze_workbook
+from linexcel.result import LineageResult, analyze
+
+__all__ = ["analyze", "LineageResult", "analyze_workbook"]

linexcel-0.1.0/src/linexcel/aidoc.py

@@ -0,0 +1,158 @@
+"""Documentation automatique des calculs par IA (google-genai / Gemini).
+
+Le modèle ne « devine » rien : chaque nœud lui est présenté avec son dossier
+déterministe issu du graphe (formule exacte, décomposition évaluée étape par
+étape, précédents et leurs valeurs, dépendants, étendue du groupe étiré,
+liens VBA). La consigne impose de ne citer que ces faits, ce qui rend la
+documentation « prouvable » : chaque affirmation renvoie à la formule ou à
+une valeur du classeur.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+DEFAULT_MODEL = "gemini-2.5-flash"
+MAX_DOSSIER_CHARS = 6_000
+
+_SYSTEM = """Tu documentes des calculs Excel pour un lecteur métier francophone.
+Pour le nœud fourni, rédige une fiche courte en Markdown :
+1. **Rôle** — une phrase sur ce que calcule la formule ;
+2. **Comment** — la logique, étape par étape, en t'appuyant STRICTEMENT sur la
+   décomposition fournie (cite les sous-expressions et leurs valeurs évaluées) ;
+3. **Sources** — d'où viennent les données (précédents, plages, noms, VBA) ;
+4. **Preuve** — la formule exacte et, si disponible, la valeur calculée.
+Règles absolues : n'invente aucune donnée ; n'affirme rien qui ne soit pas dans
+le dossier ; si une information manque, écris « non déterminé par le lignage ».
+Réponds UNIQUEMENT avec la fiche Markdown, aucun JSON, aucun délimiteur."""
+
+
+class AiDocError(RuntimeError):
+    pass
+
+
+def _client(api_key: str | None = None):
+    try:
+        from google import genai
+    except ImportError as exc:  # pragma: no cover
+        raise AiDocError(
+            "Le paquet google-genai n'est pas installé "
+            "(pip install 'backend[ai]' ou pip install google-genai)"
+        ) from exc
+    api_key = api_key or os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        raise AiDocError(
+            "Aucune clé Gemini fournie : passer api_key=... ou définir "
+            "GOOGLE_API_KEY dans l'environnement"
+        )
+    return genai.Client(api_key=api_key)
+
+
+def build_dossier(graph: dict[str, Any], node_id: str) -> dict[str, Any] | None:
+    """Dossier déterministe d'un nœud : tout ce que l'IA a le droit d'utiliser."""
+    nodes = {n["id"]: n for n in graph["nodes"]}
+    node = nodes.get(node_id)
+    if node is None:
+        return None
+    precedents, dependents = [], []
+    for e in graph["edges"]:
+        if e["target"] == node_id:
+            src = nodes.get(e["source"], {})
+            precedents.append(_neighbor(src, e))
+        elif e["source"] == node_id:
+            dst = nodes.get(e["target"], {})
+            dependents.append(_neighbor(dst, e))
+    dossier = {
+        "node_id": node_id,
+        "kind": node.get("kind"),
+        "sheet": node.get("sheet"),
+        "adresse": node.get("addr"),
+        "formule": node.get("formula"),
+        "forme_r1c1": node.get("r1c1"),
+        "cellules_du_groupe": node.get("count"),
+        "etendue": node.get("bbox"),
+        "valeur_calculee": node.get("value"),
+        "exemples_valeurs": node.get("samples"),
+        "decomposition": _compact_steps(node.get("steps")),
+        "precedents": precedents[:30],
+        "dependants": dependents[:30],
+    }
+    if node.get("kind") == "vba":
+        dossier["vba"] = {
+            "module": node.get("module"),
+            "procedure": node.get("proc"),
+            "type": node.get("procKind"),
+            "code": (node.get("code") or "")[:2500],
+        }
+    return dossier
+
+
+def _neighbor(other: dict, edge: dict) -> dict:
+    return {
+        "id": other.get("id"),
+        "kind": other.get("kind"),
+        "label": other.get("label"),
+        "lien": edge.get("kind"),
+        "valeur": other.get("value"),
+        "formule": other.get("formula"),
+    }
+
+
+def _compact_steps(step: dict | None) -> dict | None:
+    if step is None:
+        return None
+    out = {
+        "expression": step.get("expr"),
+        "operation": step.get("label"),
+        "valeur": step.get("value") if step.get("evaluated") else "non évaluée",
+    }
+    if step.get("inputs"):
+        out["entrees"] = step["inputs"]
+    children = [_compact_steps(c) for c in step.get("children", [])]
+    if children:
+        out["sous_etapes"] = children
+    return out
+
+
+def document_nodes(
+    graph: dict[str, Any],
+    node_ids: list[str],
+    model: str | None = None,
+    api_key: str | None = None,
+) -> dict[str, str]:
+    """Documente les nœuds demandés, par lots, et retourne {node_id: markdown}."""
+    client = _client(api_key)
+    model = model or os.getenv("GEMINI_MODEL", DEFAULT_MODEL)
+    docs: dict[str, str] = {}
+    dossiers = []
+    for nid in node_ids:
+        d = build_dossier(graph, nid)
+        if d is not None:
+            blob = json.dumps(d, ensure_ascii=False, default=str)
+            if len(blob) > MAX_DOSSIER_CHARS:
+                d["decomposition"] = "tronquée (formule très longue)"
+                blob = json.dumps(d, ensure_ascii=False, default=str)
+            dossiers.append((nid, blob))
+
+    for nid, blob in dossiers:
+        prompt = (
+            _SYSTEM
+            + "\n\nDossier de lignage (déterministe, extrait du classeur) :\n"
+            + blob
+        )
+        try:
+            response = client.models.generate_content(
+                model=model,
+                contents=prompt,
+                config={"temperature": 0.2},
+            )
+            text = (response.text or "").strip()
+        except AiDocError:
+            raise
+        except Exception as exc:
+            raise AiDocError(f"Appel Gemini en échec : {exc}") from exc
+        if text:
+            docs[nid] = text
+    return docs