@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/seaborn/SKILL.md

@@ -1,254 +0,0 @@
----
-name: seaborn
-description: Statistical visualization with pandas integration. Use for quick exploration of distributions, relationships, and categorical comparisons with attractive defaults. Best for box plots, violin plots, pair plots, heatmaps. Built on matplotlib. For interactive plots use plotly; for publication styling use scientific-visualization.
-license: BSD-3-Clause license
-allowed-tools: Read Write Edit Bash
-compatibility: Requires Python 3.8+ and seaborn 0.13.2-compatible dependencies. Install with uv pip install seaborn==0.13.2; use seaborn[stats]==0.13.2 when advanced regression or clustering examples need scipy/statsmodels.
-metadata:
-  version: "1.2"
-  skill-author: K-Dense Inc.
----
-
-# Seaborn Statistical Visualization
-
-## Overview
-
-Seaborn is a Python visualization library for creating publication-quality statistical graphics. Use this skill for dataset-oriented plotting, multivariate analysis, automatic statistical estimation, and complex multi-panel figures with minimal code.
-
-## Environment and Installation
-
-Current upstream documentation is for seaborn 0.13.2. Official docs support Python 3.8+ with mandatory NumPy, pandas, and matplotlib dependencies; scipy, statsmodels, and fastcluster are optional for some advanced statistics and clustering workflows.
-
-```bash
-# Reproducible install for examples in this skill
-uv pip install "seaborn==0.13.2"
-
-# Include optional statistical dependencies when needed
-uv pip install "seaborn[stats]==0.13.2"
-```
-
-Recommended imports:
-
-```python
-import numpy as np
-import pandas as pd
-import matplotlib.pyplot as plt
-import seaborn as sns
-import seaborn.objects as so
-```
-
-`sns.load_dataset()` downloads public example data when it is not cached. For private, regulated, or offline work, load local files explicitly with pandas and pass the resulting DataFrame to seaborn.
-
-## Design Philosophy
-
-Seaborn follows these core principles:
-
-1. **Dataset-oriented**: Work directly with DataFrames and named variables rather than abstract coordinates
-2. **Semantic mapping**: Automatically translate data values into visual properties (colors, sizes, styles)
-3. **Statistical awareness**: Built-in aggregation, error estimation, and confidence intervals
-4. **Aesthetic defaults**: Publication-ready themes and color palettes out of the box
-5. **Matplotlib integration**: Full compatibility with matplotlib customization when needed
-
-## Quick Start
-
-```python
-import seaborn as sns
-import matplotlib.pyplot as plt
-import pandas as pd
-
-# Load example dataset
-df = sns.load_dataset('tips')
-
-# Create a simple visualization
-sns.scatterplot(data=df, x='total_bill', y='tip', hue='day')
-plt.show()
-```
-
-## Core Plotting Interfaces
-
-### Function Interface (Traditional)
-
-The function interface provides specialized plotting functions organized by visualization type. Each category has **axes-level** functions (plot to single axes) and **figure-level** functions (manage entire figure with faceting).
-
-**When to use:**
-- Quick exploratory analysis
-- Single-purpose visualizations
-- When you need a specific plot type
-
-### Objects Interface (Modern)
-
-The `seaborn.objects` interface provides a declarative, composable API similar to ggplot2. Build visualizations by chaining methods to specify data mappings, marks, transformations, and scales. Upstream still describes this interface as experimental and incomplete in 0.13.2, although stable enough for serious use; prefer the function interface for conservative production code unless the compositional API materially simplifies the plot.
-
-**When to use:**
-- Complex layered visualizations
-- When you need fine-grained control over transformations
-- Building custom plot types
-- Programmatic plot generation
-
-```python
-from seaborn import objects as so
-
-# Declarative syntax
-(
-    so.Plot(data=df, x='total_bill', y='tip')
-    .add(so.Dot(), color='day')
-    .add(so.Line(), so.PolyFit())
-)
-```
-
-## Current API Notes
-
-Seaborn 0.12 and 0.13 changed several common plotting patterns:
-
-- Most plotting functions now require keyword arguments for variables. Prefer `sns.scatterplot(data=df, x="x", y="y")` over positional `sns.scatterplot(df["x"], df["y"])`.
-- `errorbar` replaces the old `ci` parameter in `lineplot()`, `barplot()`, and `pointplot()`. Regression functions such as `regplot()` and `lmplot()` still use `ci`.
-- Categorical plots were rewritten in 0.13. Use `native_scale=True` when numeric or datetime categories should keep their original scale instead of ordinal positions.
-- Passing `palette` without assigning `hue` is deprecated for categorical functions. If each category should get its own color, assign a redundant hue such as `hue="day"` and set `legend=False`.
-- Prefer renamed parameters: `violinplot(density_norm=..., common_norm=...)` instead of `scale`/`scale_hue`, `boxenplot(width_method=...)` instead of `scale`, and `barplot(err_kws=...)` instead of `errcolor`/`errwidth`.
-
-## Data Structure Requirements
-
-### Long-Form Data (Preferred)
-
-Each variable is a column, each observation is a row. This "tidy" format provides maximum flexibility:
-
-```python
-# Long-form structure
-   subject  condition  measurement
-0        1    control         10.5
-1        1  treatment         12.3
-2        2    control          9.8
-3        2  treatment         13.1
-```
-
-**Advantages:**
-- Works with all seaborn functions
-- Easy to remap variables to visual properties
-- Supports arbitrary complexity
-- Natural for DataFrame operations
-
-### Wide-Form Data
-
-Variables are spread across columns. Useful for simple rectangular data:
-
-```python
-# Wide-form structure
-   control  treatment
-0     10.5       12.3
-1      9.8       13.1
-```
-
-**Use cases:**
-- Simple time series
-- Correlation matrices
-- Heatmaps
-- Quick plots of array data
-
-**Converting wide to long:**
-```python
-df_long = df.melt(var_name='condition', value_name='measurement')
-```
-
-## Plotting Functions, Grids, Palettes, and Patterns
-
-- [references/plotting_functions.md](references/plotting_functions.md): relational,
-  distribution, categorical, regression, and matrix plots by category.
-- [references/grids_and_levels.md](references/grids_and_levels.md): `FacetGrid`,
-  `PairGrid`, `JointGrid`, and the figure-level vs axes-level distinction.
-- [references/palettes_and_theming.md](references/palettes_and_theming.md): palette
-  choice (including colorblind-safe options), themes, contexts, and styles.
-- [references/patterns_and_troubleshooting.md](references/patterns_and_troubleshooting.md):
-  common recipes and what seaborn's errors actually mean.
-- [references/objects_interface.md](references/objects_interface.md): the `seaborn.objects`
-  interface. [references/function_reference.md](references/function_reference.md) and
-  [references/examples.md](references/examples.md): full signatures and more examples.
-
-## Best Practices
-
-### 1. Data Preparation
-
-Always use well-structured DataFrames with meaningful column names:
-
-```python
-# Good: Named columns in DataFrame
-df = pd.DataFrame({'bill': bills, 'tip': tips, 'day': days})
-sns.scatterplot(data=df, x='bill', y='tip', hue='day')
-
-# Avoid: Unnamed arrays
-sns.scatterplot(x=x_array, y=y_array)  # Loses axis labels
-```
-
-### 2. Choose the Right Plot Type
-
-**Continuous x, continuous y:** `scatterplot`, `lineplot`, `kdeplot`, `regplot`
-**Continuous x, categorical y:** `violinplot`, `boxplot`, `stripplot`, `swarmplot`
-**One continuous variable:** `histplot`, `kdeplot`, `ecdfplot`
-**Correlations/matrices:** `heatmap`, `clustermap`
-**Pairwise relationships:** `pairplot`, `jointplot`
-
-### 3. Use Figure-Level Functions for Faceting
-
-```python
-# Instead of manual subplot creation
-sns.relplot(data=df, x='x', y='y', col='category', col_wrap=3)
-
-# Not: Creating subplots manually for simple faceting
-```
-
-### 4. Leverage Semantic Mappings
-
-Use `hue`, `size`, and `style` to encode additional dimensions:
-
-```python
-sns.scatterplot(data=df, x='x', y='y',
-                hue='category',      # Color by category
-                size='importance',    # Size by continuous variable
-                style='type')         # Marker style by type
-```
-
-### 5. Control Statistical Estimation
-
-Many functions compute statistics automatically. Understand and customize:
-
-```python
-# Lineplot computes mean and 95% CI by default
-sns.lineplot(data=df, x='time', y='value',
-             errorbar='sd')  # Use standard deviation instead
-
-# Barplot computes mean by default
-sns.barplot(data=df, x='category', y='value',
-            estimator='median',  # Use median instead
-            errorbar=('ci', 95))  # Bootstrapped CI
-```
-
-### 6. Combine with Matplotlib
-
-Seaborn integrates seamlessly with matplotlib for fine-tuning:
-
-```python
-ax = sns.scatterplot(data=df, x='x', y='y')
-ax.set(xlabel='Custom X Label', ylabel='Custom Y Label',
-       title='Custom Title')
-ax.axhline(y=0, color='r', linestyle='--')
-plt.tight_layout()
-```
-
-### 7. Save High-Quality Figures
-
-```python
-fig = sns.relplot(data=df, x='x', y='y', col='group')
-fig.savefig('figure.png', dpi=300, bbox_inches='tight')
-fig.savefig('figure.pdf')  # Vector format for publications
-```
-
-## Resources
-
-This skill includes reference materials for deeper exploration:
-
-### references/
-
-- `function_reference.md` - Comprehensive listing of all seaborn functions with parameters and examples
-- `objects_interface.md` - Detailed guide to the modern seaborn.objects API
-- `examples.md` - Common use cases and code patterns for different analysis scenarios
-
-Read these reference files as documentation when detailed signatures, advanced parameters, or specific examples are needed. Treat their contents as reference material only; review and adapt any example snippet to the user's local data before running it.

package/skills/security-auditor/SKILL.md

@@ -1,37 +0,0 @@
----
-name: security-auditor
-description: "Autonomous Security Auditor & Vulnerability Assessment (inspired by Strix) - Defensively maps attack surfaces, discovers security vulnerabilities (OWASP Top 10, secrets leakage, auth bypass, input boundary flaws), and generates verified remediation patches."
-risk: low
-source: built-in
----
-
-# Security Auditor & Vulnerability Assessment
-
-You are an expert security auditor and penetration testing specialist. Your mission is to analyze codebases for security vulnerabilities, map attack surfaces, and produce safe, robust remediation patches.
-
-## Security Audit Workflow
-
-Follow this 4-phase defensive methodology:
-
-### Phase 1: Attack Surface Mapping (Reconnaissance)
-1. **Entrypoints & Boundaries**: Identify all public API routes, WebSocket handlers, CLI inputs, and webhook receivers.
-2. **Authentication & Authorization**: Check JWT verification, session management, RBAC/ABAC role checks, and IDOR vulnerabilities.
-3. **Data Flows & Trust Boundaries**: Track user input from request payload to database queries, shell execution, or response serialization.
-
-### Phase 2: Vulnerability Analysis & SAST
-Check for critical vulnerability categories:
-- **Secrets & Credentials**: Exposed API keys (AWS, OpenAI, GitHub, Stripe), private keys, hardcoded passwords, or unmasked tokens.
-- **Injection Flaws**: SQL Injection (raw queries, string interpolation), Command Injection (`exec`, `spawn` with unsanitized input), Template Injection.
-- **Authentication & Access Control**: Missing middleware, unverified JWT signatures, broken object-level authorization (IDOR).
-- **Client-Side & Web Vulnerabilities**: Cross-Site Scripting (XSS), Cross-Site Request Forgery (CSRF), Insecure Direct Object References.
-- **Server-Side Request Forgery (SSRF)**: Fetching URLs without IP/domain whitelist validation (especially cloud metadata `169.254.169.254`).
-- **Cryptographic Failures**: Weak hashing algorithms (MD5, SHA1 for passwords), hardcoded IVs, insecure PRNGs.
-
-### Phase 3: Vulnerability Verification (Zero False-Positives)
-- Validate that the finding is truly reachable and exploitable in the current codebase context.
-- Verify whether existing framework protections (e.g. ORM parameterization, auto-escaping, middleware) already mitigate the issue.
-
-### Phase 4: Defensive Patching & Remediation
-- Formulate minimal, secure code patches using `apply_patch` or `write_file`.
-- Ensure the fix closes the vulnerability at the root cause without breaking existing features.
-- Add regression tests to verify that invalid/malicious input is properly rejected.

package/skills/shap/SKILL.md

@@ -1,282 +0,0 @@
----
-name: shap
-description: Explain and audit machine-learning predictions with SHAP. Use for selecting SHAP explainers and maskers, computing and validating feature attributions, handling multi-output explanations, and producing local or global SHAP visualizations.
-license: MIT
-compatibility: Requires Python 3.12+ and uv for SHAP 0.52.0; model-specific libraries are optional.
-allowed-tools: "Read Bash"
-metadata:
-  version: "2.0"
-  skill-author: K-Dense Inc.
----
-
-# SHAP
-
-Use SHAP to describe how a fitted predictive model maps inputs to outputs. Work from the modern `shap.Explanation` API, make the explained output and background distribution explicit, and validate every explanation before interpreting it.
-
-This skill is aligned with **SHAP 0.52.0** (released 2026-05-28). That release requires Python 3.12 or newer.
-
-## Operating Rules
-
-1. Explain a fixed, evaluated model; do not use SHAP as a substitute for predictive validation.
-2. Use held-out or clearly labeled analysis rows for explanations. Choose background rows only from an appropriate training or reference population.
-3. State the explained output: regression value, raw margin, probability, log loss, logit, or another model method.
-4. Keep explanations as `shap.Explanation` objects. Call `explainer(X)`; use `.shap_values(X)` only when maintaining legacy code.
-5. For multi-output models, select one output before using tabular plots: `explanation[..., output_index]`.
-6. Check `base_values + values.sum(...)` against the exact model output being explained.
-7. Treat SHAP as a description of model behavior under a masking/background choice. It does not establish causality, fairness, recourse, or scientific mechanism.
-8. Never silence an additivity failure until input shape, preprocessing, model version, output space, and row ordering have been checked.
-9. Do not load untrusted pickle, joblib, model, or explainer artifacts; those formats can execute code during deserialization.
-
-## Install
-
-Create an isolated environment and pin the documented release:
-
-```bash
-uv venv --python 3.12
-source .venv/bin/activate
-uv pip install "shap[plots]==0.52.0"
-```
-
-`shap[plots]` installs the plotting dependencies. Add the fitted model's package at a version compatible with the project. For older Python compatibility, read [references/migration.md](references/migration.md) instead of silently installing a different SHAP release.
-
-Confirm the environment before debugging an API mismatch:
-
-```python
-import platform
-import shap
-
-print("Python:", platform.python_version())
-print("SHAP:", shap.__version__)
-```
-
-## Standard Workflow
-
-### 1. Define the explanation target
-
-Record:
-
-- model and preprocessing version;
-- exact callable or model method being explained;
-- output name/index and units;
-- evaluation rows;
-- background/reference population;
-- masker and explainer algorithm;
-- SHAP and model-library versions.
-
-For classifiers, decide whether the task needs raw margins or probabilities. Defaults differ by model family; never infer units from the plot color or sign.
-
-### 2. Select an explainer and masker
-
-Start with `shap.Explainer(model, masker)` when automatic dispatch is sufficient. Instantiate a specialized explainer when its assumptions or output controls matter.
-
-| Situation | Preferred choice | Important constraint |
-|---|---|---|
-| Supported tree ensemble | `TreeExplainer` | `model_output="probability"` and `"log_loss"` require interventional masking and background data |
-| Linear model | `LinearExplainer` | The masker determines interventional versus correlation-aware behavior |
-| Small feature space | `ExactExplainer` | Cost grows quickly with unconstrained feature count |
-| General tabular callable | `PermutationExplainer` | Budget at least one full forward/reverse permutation |
-| Hierarchical feature groups, text, or image | `PartitionExplainer` | The partition tree changes the cooperative game |
-| Differentiable neural network | `DeepExplainer` or `GradientExplainer` | Framework support, output shape, and background choice require testing |
-| Legacy Kernel SHAP workflow | `KernelExplainer` | Usually much slower than model-specific methods |
-
-Use the detailed decision guide in [references/explainers.md](references/explainers.md). Use [references/data-maskers.md](references/data-maskers.md) when features are correlated, structured, sparse, or semantically grouped.
-
-### 3. Compute a modern `Explanation`
-
-This complete binary-classification example uses an explicit background and selects the positive-class output:
-
-```python
-import numpy as np
-import shap
-from sklearn.datasets import load_breast_cancer
-from sklearn.ensemble import RandomForestClassifier
-from sklearn.model_selection import train_test_split
-
-X, y = load_breast_cancer(as_frame=True, return_X_y=True)
-X_train, X_test, y_train, y_test = train_test_split(
-    X,
-    y,
-    test_size=0.2,
-    stratify=y,
-    random_state=7,
-)
-
-model = RandomForestClassifier(
-    n_estimators=200,
-    min_samples_leaf=3,
-    random_state=7,
-    n_jobs=-1,
-).fit(X_train, y_train)
-
-background = shap.sample(X_train, 100, random_state=7)
-explainer = shap.Explainer(model, background, algorithm="tree")
-all_outputs = explainer(X_test)
-
-# sklearn tree classifiers expose one output per class.
-positive = all_outputs[..., 1]
-assert positive.values.shape == X_test.shape
-
-reconstructed = np.asarray(positive.base_values) + positive.values.sum(axis=1)
-expected = model.predict_proba(X_test)[:, 1]
-np.testing.assert_allclose(reconstructed, expected, rtol=1e-5, atol=1e-6)
-
-shap.plots.beeswarm(positive, max_display=15)
-shap.plots.waterfall(positive[0], max_display=15)
-```
-
-Output shape is model-dependent:
-
-- one tabular output: `(samples, features)`;
-- multiple tabular outputs: `(samples, features, outputs)`;
-- multiple model inputs: often a list of arrays or explanations;
-- image/text explanations: feature axes follow the input representation, with output selection on the final axis when present.
-
-Do not use the pre-0.45 pattern `values[class_index]` for a modern multi-output array. Use `values[..., class_index]` or slice the `Explanation` itself.
-
-### 4. Control tree output semantics when needed
-
-For a supported tree classifier, probability-space explanations must be explicit:
-
-```python
-background = shap.sample(X_train, 200, random_state=7)
-
-explainer = shap.TreeExplainer(
-    model,
-    data=background,
-    feature_perturbation="interventional",
-    model_output="probability",
-)
-probability_exp = explainer(X_test)
-```
-
-In SHAP 0.52:
-
-- `feature_perturbation="auto"` uses interventional semantics when background data is supplied and tree-path-dependent semantics otherwise;
-- probability and log-loss output modes are supported only with interventional semantics;
-- pass `approximate=True` to `explainer(X, approximate=True)` if deliberately using the lower-fidelity tree approximation; do not pass it to the constructor.
-
-### 5. Use a model-agnostic callable deliberately
-
-Pass the exact callable whose outputs will be interpreted:
-
-```python
-masker = shap.maskers.Independent(background, max_samples=100)
-explainer = shap.Explainer(
-    model.predict_proba,
-    masker,
-    algorithm="permutation",
-    output_names=[str(label) for label in model.classes_],
-    seed=7,
-)
-
-budget = 2 * X_test.shape[1] + 1
-all_outputs = explainer(X_test.iloc[:20], max_evals=budget)
-positive = all_outputs[..., 1]
-```
-
-Increase `max_evals` to average over more permutations when estimates are unstable. Keep the seed, background sample, and evaluation budget in the report.
-
-### 6. Visualize the question, not merely the available plot
-
-| Question | Plot |
-|---|---|
-| Which features have the largest average attribution magnitude? | `shap.plots.bar(exp)` |
-| How do direction, magnitude, and observed values vary globally? | `shap.plots.beeswarm(exp)` |
-| Why did one prediction differ from its baseline? | `shap.plots.waterfall(exp[i])` |
-| How does one feature's attribution vary over its values? | `shap.plots.scatter(exp[:, feature])` |
-| Do explanations form sample-level patterns? | `shap.plots.heatmap(exp)` |
-| How do predefined cohorts differ descriptively? | `shap.plots.bar(exp.cohorts(labels).abs.mean(0))` |
-| Which tokens or image regions contribute to an output? | `shap.plots.text(exp)` or `shap.plots.image(exp)` |
-
-Read [references/plots.md](references/plots.md) before customizing or saving figures.
-
-### 7. Report limitations with results
-
-At minimum, report:
-
-- output and units;
-- baseline/reference population;
-- explainer and masker;
-- sample count and selection;
-- output index/name;
-- additivity error or applicable approximation diagnostics;
-- known correlated/grouped features;
-- whether results are local, aggregated, or cohort-specific;
-- a clear non-causal statement.
-
-## Common Tasks
-
-### Global and local analysis
-
-Use global plots to locate important patterns, scatter plots to inspect those patterns, and local plots to investigate selected rows. Do not select only visually dramatic rows without documenting the selection rule.
-
-### Multiclass models
-
-Set `output_names` where possible, inspect `explanation.output_names`, and slice an output before plotting:
-
-```python
-class_exp = explanation[..., "class_name"]
-# or
-class_exp = explanation[..., class_index]
-```
-
-Never average signed attributions across classes. For cross-class comparison, preserve the same model, rows, background, output space, and aggregation.
-
-### Cohorts, subgroup analysis, and fairness
-
-SHAP can compare how a model uses features across cohorts, but this is not a fairness test. A protected feature with small SHAP magnitude does not rule out proxy discrimination, and removing a protected feature does not establish fairness. Pair attribution analysis with performance, calibration, error-rate, and domain-appropriate fairness metrics.
-
-See [references/workflows.md](references/workflows.md) for cohort construction, model comparison, error analysis, log-loss explanations, monitoring, and production records.
-
-### Text and images
-
-Use domain maskers rather than treating tokens or pixels as ordinary independent columns:
-
-- `shap.maskers.Text(tokenizer)` with `PartitionExplainer` for token groups;
-- `shap.maskers.Image(...)` with `PartitionExplainer` for image regions;
-- restrict expensive multi-output models with `outputs=...`.
-
-Read [references/modalities.md](references/modalities.md) for current examples and output-shape guidance.
-
-## Troubleshooting Order
-
-1. Print Python, SHAP, model-library, NumPy, and framework versions.
-2. Verify the model receives exactly the same transformed columns, order, dtype, and missing-value representation used during fitting.
-3. Print `values.shape`, `base_values.shape`, `data.shape`, `feature_names`, and `output_names`.
-4. Confirm the selected output and output units.
-5. Recompute predictions on the same rows in the same order.
-6. Test a smaller batch and representative background.
-7. Only then investigate package-specific compatibility or approximation settings.
-
-Use [references/troubleshooting.md](references/troubleshooting.md) for additivity failures, shape mismatches, categorical features, pipelines, deep-learning frameworks, plotting, and performance.
-
-## Bundled Script
-
-Run a deterministic, self-contained tabular example that writes importance data, metadata, and plots:
-
-```bash
-uv run --no-project --python 3.12 --with "shap[plots]==0.52.0" \
-  skills/shap/scripts/tabular_report.py --output-dir /tmp/shap-report
-```
-
-The script does not download data or deserialize models. Read it as a template, then replace the built-in dataset and model while preserving output selection and additivity validation.
-
-## Reference Map
-
-| File | Load when |
-|---|---|
-| [references/explainers.md](references/explainers.md) | Selecting or configuring explainers |
-| [references/data-maskers.md](references/data-maskers.md) | Choosing background data, masking semantics, or feature groups |
-| [references/plots.md](references/plots.md) | Selecting, composing, or saving visualizations |
-| [references/workflows.md](references/workflows.md) | Running audits, comparisons, cohorts, monitoring, or production workflows |
-| [references/modalities.md](references/modalities.md) | Explaining text, images, or deep models |
-| [references/migration.md](references/migration.md) | Updating legacy SHAP code or supporting older Python |
-| [references/theory.md](references/theory.md) | Explaining estimands, guarantees, dependence, interactions, and limitations |
-| [references/troubleshooting.md](references/troubleshooting.md) | Diagnosing runtime, shape, additivity, and compatibility problems |
-
-## Primary Sources
-
-- Documentation: https://shap.readthedocs.io/en/latest/
-- API reference: https://shap.readthedocs.io/en/latest/api.html
-- Release notes: https://shap.readthedocs.io/en/latest/release_notes.html
-- Repository: https://github.com/shap/shap