@bcelep/capint 0.4.2 → 0.6.5

package/skills/xlsx/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: xlsx
+description: 'Spreadsheet reading, data analysis, visualization, and smart editing toolkit. Use when the agent needs to: (1) Read and inspect .xlsx/.xlsm/.csv/.tsv files — structure, sheets, cell ranges, (2) Profile and analyze data — statistics, distributions, anomalies, correlations, (3) Query and filter data with pandas, (4) Generate charts and visual summaries from spreadsheet data, (5) Create or edit Excel files with formulas and formatting, or (6) Recalculate and verify formula integrity.'
+metadata:
+  version: '2.0.1'
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Spreadsheet Analyst Toolkit
+
+## Reading & Inspection
+
+### Quick Peek — Structure and Shape
+
+Understand what a file contains before diving into analysis.
+
+```python
+import openpyxl, pandas as pd
+
+wb = openpyxl.load_workbook("file.xlsx", read_only=True, data_only=True)
+for name in wb.sheetnames:
+    ws = wb[name]
+    print(f"[{name}] rows={ws.max_row} cols={ws.max_column}")
+wb.close()
+
+sheets = pd.read_excel("file.xlsx", sheet_name=None, nrows=0)
+for name, df in sheets.items():
+    print(f"[{name}] columns: {list(df.columns)}")
+```
+
+### Load Data
+
+```python
+import pandas as pd
+
+df = pd.read_excel("file.xlsx")
+df = pd.read_excel("file.xlsx", sheet_name="Sales")
+all_sheets = pd.read_excel("file.xlsx", sheet_name=None)
+
+df = pd.read_csv("data.csv")
+df = pd.read_csv("data.tsv", sep="\t")
+
+# Large files — limit columns and rows
+df = pd.read_excel("big.xlsx", usecols=["A", "B", "D"], nrows=5000)
+
+# Type control
+df = pd.read_excel("file.xlsx", dtype={"id": str, "amount": float}, parse_dates=["date"])
+```
+
+### Inspect Raw Cells (openpyxl)
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("file.xlsx", data_only=True)
+ws = wb.active
+
+for row in ws.iter_rows(min_row=1, max_row=5, values_only=False):
+    for cell in row:
+        print(f"{cell.coordinate}: {cell.value} (type={type(cell.value).__name__})")
+
+# Read formulas (not computed values)
+wb_f = load_workbook("file.xlsx", data_only=False)
+ws_f = wb_f.active
+print(ws_f["B2"].value)  # e.g. "=SUM(B3:B10)"
+```
+
+## Data Analysis
+
+### Profiling — Overview of Each Column
+
+```python
+df.info()
+df.describe(include="all")
+df.dtypes
+df.isnull().sum()
+df.nunique()
+```
+
+### Distribution & Outliers
+
+```python
+col = "revenue"
+print(df[col].quantile([0.01, 0.25, 0.5, 0.75, 0.99]))
+
+iqr = df[col].quantile(0.75) - df[col].quantile(0.25)
+lower, upper = df[col].quantile(0.25) - 1.5 * iqr, df[col].quantile(0.75) + 1.5 * iqr
+outliers = df[(df[col] < lower) | (df[col] > upper)]
+print(f"Outliers: {len(outliers)} / {len(df)}")
+```
+
+### Correlation
+
+```python
+numeric_cols = df.select_dtypes(include="number")
+corr = numeric_cols.corr()
+print(corr.to_string())
+```
+
+### Grouping & Aggregation
+
+```python
+summary = df.groupby("category").agg(
+    count=("id", "count"),
+    total=("amount", "sum"),
+    avg=("amount", "mean"),
+).sort_values("total", ascending=False)
+```
+
+### Pivot Tables
+
+```python
+pivot = df.pivot_table(
+    values="amount",
+    index="region",
+    columns="quarter",
+    aggfunc=["sum", "mean"],
+    margins=True,
+)
+```
+
+### Time Series
+
+```python
+df["date"] = pd.to_datetime(df["date"])
+monthly = df.set_index("date").resample("M")["value"].agg(["sum", "mean", "count"])
+yoy = monthly["sum"].pct_change(12)
+```
+
+### Deduplication & Cleaning
+
+```python
+dupes = df[df.duplicated(subset=["email"], keep=False)]
+df_clean = df.drop_duplicates(subset=["email"], keep="last")
+df_clean["name"] = df_clean["name"].str.strip().str.title()
+```
+
+## Visualization
+
+Generate charts and save to file. Prefer matplotlib for static charts.
+
+```python
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=(10, 6))
+summary.plot.bar(y="total", ax=ax)
+ax.set_title("Total by Category")
+ax.set_ylabel("Amount")
+fig.tight_layout()
+fig.savefig("chart.png", dpi=150)
+plt.close(fig)
+```
+
+Common chart patterns:
+
+```python
+# Line — trend
+df.plot(x="date", y="revenue", ax=ax)
+
+# Scatter — correlation
+df.plot.scatter(x="spend", y="revenue", ax=ax, alpha=0.5)
+
+# Histogram — distribution
+df["score"].plot.hist(bins=30, ax=ax)
+
+# Heatmap — correlation matrix
+import seaborn as sns
+sns.heatmap(corr, annot=True, fmt=".2f", ax=ax)
+
+# Box — outlier overview
+df.boxplot(column="amount", by="category", ax=ax)
+```
+
+## Creating & Editing Excel Files
+
+### New Workbook
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment, numbers
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Report"
+
+ws["A1"] = "Category"
+ws["B1"] = "Amount"
+for cell in ws[1]:
+    cell.font = Font(bold=True, color="FFFFFF")
+    cell.fill = PatternFill("solid", fgColor="4472C4")
+    cell.alignment = Alignment(horizontal="center")
+
+for i, (cat, amt) in enumerate([("A", 100), ("B", 200)], start=2):
+    ws[f"A{i}"] = cat
+    ws[f"B{i}"] = amt
+
+ws[f"B{i+1}"] = f"=SUM(B2:B{i})"
+ws.column_dimensions["A"].width = 18
+ws.column_dimensions["B"].width = 14
+ws[f"B2"].number_format = '#,##0'
+
+wb.save("report.xlsx")
+```
+
+### Edit Existing File
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("existing.xlsx")
+ws = wb["Sheet1"]
+ws["A1"] = "Updated"
+ws.insert_rows(2)
+wb.save("modified.xlsx")
+```
+
+### Formula Rules
+
+- Use Excel formulas, not Python-computed values
+- Place assumptions in dedicated cells with references
+- Verify no #REF!, #DIV/0!, #VALUE!, #NAME? after saving
+
+```python
+# Correct
+ws["C2"] = "=A2*B2"
+ws["C10"] = "=SUM(C2:C9)"
+
+# Wrong — hardcoded
+total = sum(values)
+ws["C10"] = total
+```
+
+### Recalculate Formulas
+
+After writing formulas, use the bundled formula engine:
+
+```bash
+# Recalculate + audit (default)
+python scripts/formula_engine.py output.xlsx
+
+# Audit only — scan errors without recalculating
+python scripts/formula_engine.py output.xlsx --audit-only
+
+# Show formula dependency map
+python scripts/formula_engine.py output.xlsx --deps
+
+# Custom LibreOffice timeout
+python scripts/formula_engine.py output.xlsx --timeout 60
+```
+
+Returns per-sheet breakdown:
+
+```json
+{
+  "status": "clean",
+  "sheets": {
+    "Sheet1": { "cells": 500, "formulas": 42, "errors": {} }
+  },
+  "totals": { "formulas": 42, "errors": 0 }
+}
+```
+
+If `has_errors`, check each sheet's `errors` dict for error types and cell locations, fix source formulas, re-save, and recalculate again.
+
+## Financial Model Standards
+
+Apply these only when building financial models.
+
+### Color Conventions
+
+| Cell Content      | Color                         |
+| ----------------- | ----------------------------- |
+| Hardcoded inputs  | Blue text (0,0,255)           |
+| Formulas          | Black text (0,0,0)            |
+| Cross-sheet links | Green text (0,128,0)          |
+| External links    | Red text (255,0,0)            |
+| Key assumptions   | Yellow background (255,255,0) |
+
+### Number Formats
+
+| Data Type   | Format                                  |
+| ----------- | --------------------------------------- |
+| Currency    | `$#,##0;($#,##0);"-"` (units in header) |
+| Percentage  | `0.0%`                                  |
+| Multiples   | `0.0x`                                  |
+| Year labels | Text, not number                        |
+| Negatives   | Parentheses `(123)` not `-123`          |
+
+## Quick Lookup
+
+| Goal                            | Tool                      | Key API                                      |
+| ------------------------------- | ------------------------- | -------------------------------------------- |
+| Read data into DataFrame        | pandas                    | `pd.read_excel()`                            |
+| Column stats & profiling        | pandas                    | `df.describe()`, `df.info()`                 |
+| Group / pivot / aggregate       | pandas                    | `df.groupby()`, `df.pivot_table()`           |
+| Inspect raw cells / formulas    | openpyxl                  | `load_workbook(data_only=False)`             |
+| Charts                          | matplotlib                | `df.plot()`, `plt.savefig()`                 |
+| Heatmaps                        | seaborn                   | `sns.heatmap()`                              |
+| Create workbook with formatting | openpyxl                  | `Workbook()` + styles                        |
+| Recalculate + audit formulas    | scripts/formula_engine.py | `python scripts/formula_engine.py file.xlsx` |
+| Audit formulas only             | scripts/formula_engine.py | `--audit-only`                               |
+| Formula dependency map          | scripts/formula_engine.py | `--deps`                                     |
+| Large file reading              | pandas                    | `usecols=`, `nrows=`, `read_only=True`       |
+| CSV / TSV                       | pandas                    | `pd.read_csv()`                              |
+
+## Advanced
+
+For advanced analysis workflows, specialized techniques, and troubleshooting:
+
+- **Multi-sheet cross analysis**: See [references/advanced-analysis.md](references/advanced-analysis.md)
+- **Data quality audit pipeline**: See [references/advanced-analysis.md](references/advanced-analysis.md)
+- **Merge and join strategies**: See [references/advanced-analysis.md](references/advanced-analysis.md)
+- **Performance tuning for large files**: See [references/advanced-analysis.md](references/advanced-analysis.md)
+- **Troubleshooting common issues**: See [references/advanced-analysis.md](references/advanced-analysis.md)

package/skills/xlsx/agents/verdent.yaml

@@ -0,0 +1,9 @@
+category: Media & Files
+interface:
+  display_name: 'Spreadsheet'
+  short_description: 'Create, edit, and analyze spreadsheets'
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: 'Create, edit, or analyze this spreadsheet and summarize key insights or changes.'
+  builtin: true
+  hidden: true

package/skills/xlsx/references/advanced-analysis.md

@@ -0,0 +1,272 @@
+# Advanced Spreadsheet Analysis Reference
+
+Supplementary patterns for complex analysis tasks. Load only when SKILL.md guidance is insufficient.
+
+## Table of Contents
+
+- [Multi-Sheet Cross Analysis](#multi-sheet-cross-analysis)
+- [Data Quality Audit Pipeline](#data-quality-audit-pipeline)
+- [Merge and Join Strategies](#merge-and-join-strategies)
+- [Fuzzy Matching](#fuzzy-matching)
+- [Window Functions & Rolling Calculations](#window-functions--rolling-calculations)
+- [Performance Tuning for Large Files](#performance-tuning-for-large-files)
+- [Writing Analysis Results Back to Excel](#writing-analysis-results-back-to-excel)
+- [Troubleshooting](#troubleshooting)
+
+## Multi-Sheet Cross Analysis
+
+Combine data from multiple sheets or workbooks for unified analysis.
+
+```python
+import pandas as pd
+
+all_sheets = pd.read_excel("workbook.xlsx", sheet_name=None)
+combined = pd.concat(all_sheets.values(), keys=all_sheets.keys(), names=["sheet"])
+combined = combined.reset_index(level="sheet")
+
+# Cross-file merge
+df_a = pd.read_excel("sales.xlsx")
+df_b = pd.read_excel("targets.xlsx")
+merged = df_a.merge(df_b, on="region", how="left", suffixes=("_actual", "_target"))
+merged["variance"] = merged["revenue_actual"] - merged["revenue_target"]
+merged["pct_var"] = merged["variance"] / merged["revenue_target"]
+```
+
+### Compare Two Versions of a Sheet
+
+```python
+old = pd.read_excel("report_v1.xlsx")
+new = pd.read_excel("report_v2.xlsx")
+
+# Cell-by-cell diff
+diff = old.compare(new, keep_shape=True, keep_equal=False)
+print(diff.dropna(how="all"))
+```
+
+## Data Quality Audit Pipeline
+
+Run a structured quality check to surface problems before analysis.
+
+```python
+def audit(df):
+    report = {}
+    report["rows"] = len(df)
+    report["columns"] = len(df.columns)
+    report["duplicated_rows"] = df.duplicated().sum()
+
+    missing = df.isnull().sum()
+    report["missing"] = missing[missing > 0].to_dict()
+
+    report["constant_cols"] = [c for c in df.columns if df[c].nunique() <= 1]
+
+    numeric = df.select_dtypes(include="number")
+    for col in numeric.columns:
+        q1, q3 = numeric[col].quantile(0.25), numeric[col].quantile(0.75)
+        iqr = q3 - q1
+        n_out = ((numeric[col] < q1 - 1.5 * iqr) | (numeric[col] > q3 + 1.5 * iqr)).sum()
+        if n_out > 0:
+            report.setdefault("outliers", {})[col] = int(n_out)
+
+    for col in df.select_dtypes(include="object").columns:
+        mixed = df[col].dropna().apply(type).nunique()
+        if mixed > 1:
+            report.setdefault("mixed_types", []).append(col)
+
+    return report
+```
+
+### Automated Checks Checklist
+
+| Check                     | Expression                             |
+| ------------------------- | -------------------------------------- |
+| Missing values per column | `df.isnull().sum()`                    |
+| Duplicate rows            | `df.duplicated().sum()`                |
+| Unique counts             | `df.nunique()`                         |
+| Negative where unexpected | `(df[col] < 0).sum()`                  |
+| Date range validity       | `df["date"].between(start, end).all()` |
+| Format consistency        | `df[col].str.match(pattern).all()`     |
+
+## Merge and Join Strategies
+
+```python
+# Inner join — only matching keys
+merged = left.merge(right, on="key")
+
+# Left join — keep all left rows
+merged = left.merge(right, on="key", how="left")
+
+# Multi-key join
+merged = left.merge(right, on=["region", "date"])
+
+# Join on different column names
+merged = left.merge(right, left_on="emp_id", right_on="employee_id")
+
+# Validate uniqueness
+merged = left.merge(right, on="key", validate="one_to_one")
+
+# Indicator column shows match source
+merged = left.merge(right, on="key", how="outer", indicator=True)
+unmatched = merged[merged["_merge"] != "both"]
+```
+
+## Fuzzy Matching
+
+When keys don't align exactly (typos, casing, abbreviations).
+
+```python
+from difflib import get_close_matches
+
+def fuzzy_map(source_keys, target_keys, cutoff=0.8):
+    mapping = {}
+    for key in source_keys:
+        matches = get_close_matches(key, target_keys, n=1, cutoff=cutoff)
+        if matches:
+            mapping[key] = matches[0]
+    return mapping
+
+key_map = fuzzy_map(df_a["name"].unique(), df_b["name"].unique())
+df_a["matched_name"] = df_a["name"].map(key_map)
+merged = df_a.merge(df_b, left_on="matched_name", right_on="name", suffixes=("_a", "_b"))
+```
+
+## Window Functions & Rolling Calculations
+
+```python
+# Rolling average
+df["ma_7d"] = df["value"].rolling(7).mean()
+
+# Expanding cumulative sum
+df["cum_total"] = df["value"].expanding().sum()
+
+# Rank within group
+df["rank"] = df.groupby("category")["score"].rank(ascending=False)
+
+# Lag / lead
+df["prev_value"] = df.groupby("id")["value"].shift(1)
+df["change"] = df["value"] - df["prev_value"]
+
+# Percent change
+df["pct_change"] = df.groupby("id")["value"].pct_change()
+```
+
+## Performance Tuning for Large Files
+
+### Read Optimization
+
+```python
+# Column selection — read only what you need
+df = pd.read_excel("big.xlsx", usecols=["A", "C", "F"])
+
+# Row limit for sampling
+df = pd.read_excel("big.xlsx", nrows=10000)
+
+# openpyxl read-only mode — avoids full parse
+from openpyxl import load_workbook
+wb = load_workbook("big.xlsx", read_only=True, data_only=True)
+ws = wb.active
+for row in ws.iter_rows(min_row=1, max_row=100, values_only=True):
+    print(row)
+wb.close()
+```
+
+### Chunked CSV Processing
+
+```python
+chunks = pd.read_csv("huge.csv", chunksize=50000)
+results = []
+for chunk in chunks:
+    agg = chunk.groupby("category")["amount"].sum()
+    results.append(agg)
+final = pd.concat(results).groupby(level=0).sum()
+```
+
+### Memory Reduction
+
+```python
+# Downcast numeric types
+for col in df.select_dtypes(include="integer").columns:
+    df[col] = pd.to_numeric(df[col], downcast="integer")
+for col in df.select_dtypes(include="float").columns:
+    df[col] = pd.to_numeric(df[col], downcast="float")
+
+# Convert low-cardinality strings to category
+for col in df.select_dtypes(include="object").columns:
+    if df[col].nunique() / len(df) < 0.5:
+        df[col] = df[col].astype("category")
+```
+
+## Writing Analysis Results Back to Excel
+
+Export DataFrame results with formatting using openpyxl writer.
+
+```python
+from openpyxl.utils.dataframe import dataframe_to_rows
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Analysis"
+
+for r_idx, row in enumerate(dataframe_to_rows(summary, index=True, header=True), 1):
+    for c_idx, val in enumerate(row, 1):
+        ws.cell(row=r_idx, column=c_idx, value=val)
+
+# Style header row
+for cell in ws[1]:
+    cell.font = Font(bold=True, color="FFFFFF")
+    cell.fill = PatternFill("solid", fgColor="2F5496")
+    cell.alignment = Alignment(horizontal="center")
+
+# Auto-fit column widths (approximate)
+for col in ws.columns:
+    max_len = max(len(str(c.value or "")) for c in col)
+    ws.column_dimensions[col[0].column_letter].width = min(max_len + 2, 40)
+
+wb.save("analysis_output.xlsx")
+```
+
+## Troubleshooting
+
+### read_excel returns empty DataFrame
+
+1. Check `sheet_name` — default reads only the first sheet.
+2. Check `header` — if there is no header row, use `header=None`.
+3. Check `skiprows` — data may start below row 1.
+
+### Mixed types in a column
+
+pandas reads mixed columns as `object`. Force a type:
+
+```python
+df["col"] = pd.to_numeric(df["col"], errors="coerce")  # non-numeric -> NaN
+```
+
+### Date parsing failures
+
+```python
+df["date"] = pd.to_datetime(df["date"], format="%Y-%m-%d", errors="coerce")
+```
+
+### openpyxl data_only returns None
+
+`data_only=True` reads cached values. If the file was saved without opening in Excel, cached values may be missing. Run `scripts/recalc.py` first.
+
+### Memory issues with large files
+
+- Use `read_only=True` in openpyxl
+- Use `usecols` and `nrows` in pandas
+- Process CSV in chunks with `chunksize`
+- Downcast numeric types
+
+### Formula errors after edit
+
+Run `python scripts/recalc.py file.xlsx` and inspect the JSON output. Common errors:
+
+| Error     | Cause                          | Fix                             |
+| --------- | ------------------------------ | ------------------------------- |
+| `#REF!`   | Deleted cells still referenced | Update references               |
+| `#DIV/0!` | Zero denominator               | Add `IF(denom=0, 0, ...)` guard |
+| `#VALUE!` | Type mismatch in formula       | Check cell types                |
+| `#NAME?`  | Typo in function name          | Correct spelling                |
+| `#N/A`    | VLOOKUP/MATCH miss             | Verify lookup range             |

package/skills/xlsx/references/examples/openpyxl/create_basic_spreadsheet.py

@@ -0,0 +1,51 @@
+"""Create a basic spreadsheet with two sheets and a simple formula.
+
+Usage:
+  python3 create_basic_spreadsheet.py --output /tmp/basic_spreadsheet.xlsx
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from openpyxl import Workbook
+from openpyxl.utils import get_column_letter
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Create a basic spreadsheet with example data.")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path("basic_spreadsheet.xlsx"),
+        help="Output .xlsx path (default: basic_spreadsheet.xlsx)",
+    )
+    args = parser.parse_args()
+
+    wb = Workbook()
+    overview = wb.active
+    overview.title = "Overview"
+    employees = wb.create_sheet("Employees")
+
+    overview["A1"] = "Description"
+    overview["A2"] = "Awesome Company Report"
+
+    employees.append(["Title", "Name", "Address", "Score"])
+    employees.append(["Engineer", "Vicky", "90 50th Street", 98])
+    employees.append(["Manager", "Alex", "500 Market Street", 92])
+    employees.append(["Designer", "Jordan", "200 Pine Street", 88])
+
+    employees["A6"] = "Total Score"
+    employees["D6"] = "=SUM(D2:D4)"
+
+    for col in range(1, 5):
+        employees.column_dimensions[get_column_letter(col)].width = 20
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(args.output)
+    print(f"Saved workbook to {args.output}")
+
+
+if __name__ == "__main__":
+    main()