hermes-tabular

hermes-tabular ☤

A small, opinionated pack of Hermes skills for tabular intelligence.

Ten skills. One entry point. A deliberately narrow decision space so an agent can consistently make good choices instead of drowning in options.

Why this exists

Existing tabular tools tend to fall into two extremes. Some are too narrow, forcing a single model backend onto every dataset. Others are too wide, drowning the agent in endless hyperparameter grids, redundant gradient boosting backends, and samplers. The agent spends its token budget picking knobs instead of solving the problem.

hermes-tabular sits in the goldilocks zone: a deliberately structured decision space built on four distinct model families. It gives the agent room to adapt to your data without wasting budget on unnecessary choices:

| Family | Default | Why |
| --- | --- | --- |
| Statistical | Linear / Logistic Regression | Fast, interpretable baseline, calibration reference |
| Tree-based ML | CatBoost | Strong default for most tabular data with mixed feature types |
| Foundation Model | TabICL | Excellent for small and medium datasets with minimal tuning |
| Ensemble | Simple averaging / stacking | Frequently the best final performer |

Additional backends can be added later as new skills without touching orchestration policy.

Repository layout

hermes-tabular/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
│
├── references/
│   └── pitfalls.md
│
├── examples/
│   ├── titanic.md
│   ├── california_housing.md
│   └── churn.md
│
├── scripts/                  # human-side convenience only; agents do not need these
│   ├── install_skills.py
│   └── validate_skills.py
│
└── skills/
    ├── tabular/              # orchestrator (the only skill invoked directly)
    │   ├── SKILL.md
    │   └── defaults.yaml
    ├── tabular-inspect/
    ├── tabular-load/
    ├── tabular-split/
    ├── tabular-baseline/
    ├── tabular-catboost/
    ├── tabular-tabicl/
    ├── tabular-ensemble/
    ├── tabular-evaluate/
    ├── tabular-uncertainty/
    └── tabular-checkpoint/

Architecture Pattern

+-------------------------------------------------------------+
| System Environment (Human Administrator) |
| Handled once via pip/uv. Installs heavy binary backends: |
| - CatBoost, PyTorch, TabICL, Conformal Prediction |
+-------------------------------------------------------------+
│
▼
+-------------------------------------------------------------+
| Skill Injection (Hermes Agent / Harness) |
| Handled by running scripts/install_skills.py: |
| - Copies/symlinks markdown prompts, rules, & defaults |
+-------------------------------------------------------------+

Install

As a Hermes plugin (recommended)

If you use Hermes Agent, install the pack as a plugin. Hermes resolves the
Python environment from pyproject.toml and registers every skill
automatically, namespaced as hermes-tabular:<skill> — invoke only
hermes-tabular:tabular, the orchestrator.

hermes plugins install hermes-tabular --enable                  # once listed in the community plugin catalog
hermes plugins install frankiethull/hermes-tabular --enable     # direct from git, before catalog listing

No manual copying of skill files is needed in this mode. The two sections
below ("For Humans / System Setup" and "For Agents / Skill Deployment")
describe the manual path, which remains available for other harnesses.

Two different audiences do two different jobs here. Read only your section.

| | Who | Does what | How often |
| --- | --- | --- | --- |
| Humans | operator / maintainer | provision the Python environment | once per machine |
| Agents | Hermes | place and remove skill files in a project | per project, freely |

The split exists because installing torch and CatBoost is a privileged, heavy,
network-dependent operation that an agent should not be improvising. Copying a
directory of Markdown files is not. Keep those concerns apart and neither audience
has to think about the other's job.

For Humans / System Setup

One-time. Provision the runtime the skills assume, then get out of the way.

1. Install Python dependencies.

pip install -r requirements.txt

Or install only what you intend to use — the foundation model pulls torch and is
by far the heaviest piece:

pip install -e ".[catboost]"      # CatBoost only — lean, no GPU needed
pip install -e ".[tabicl]"        # TabICL foundation model (pulls torch)
pip install -e ".[uncertainty]"   # conformal prediction
pip install -e ".[all]"           # everything

2. Decide the TabICL question now, not at runtime.

TabICL downloads a pretrained checkpoint (a few hundred MB) on its first fit, and
wants a GPU above roughly 10,000 rows. If the target machine is air-gapped, is
CPU-only, or has no room for the checkpoint, install without the tabicl extra.
tabular-tabicl detects the missing package, reports it, and the orchestrator falls
back to CatBoost. That is a clean degradation — but it should be your decision, made
here, rather than a surprise mid-analysis.

3. Verify the pack is intact.

python scripts/validate_skills.py

Checks that every skill has valid frontmatter with name and description, that
folder names match declared names, that every tabular-* reference in the
orchestrator resolves, and that defaults.yaml parses. Run this after editing any
skill and before publishing the repo.

4. Optionally, seed a project yourself.

If you would rather hand an agent a project that already has the skills in place:

python scripts/install_skills.py add --all --target /path/to/project
python scripts/install_skills.py add --core --target /path/to/project   # lean 7-skill set
python scripts/install_skills.py list --target /path/to/project
python scripts/install_skills.py remove --all --target /path/to/project

Supports --link to symlink instead of copy (upstream edits propagate) and
--dry-run to preview. This script is ergonomics, not architecture — it does
nothing an agent could not do with cp -r. Nothing in the pack depends on it.

5. Tune policy, not prose.

skills/tabular/defaults.yaml holds every number the orchestrator relies on: dataset
size bands, CV folds, metric choices, the ensemble adoption threshold, time budgets.
Edit values there to change agent behavior across the whole pack. This is the
intended customization surface.

For Agents / Skill Deployment

Hermes installs these skills on its own. No human is in this loop.

Add skills to the current project. They are plain directories of Markdown; a
copy is the whole operation.

mkdir -p .hermes/skills
cp -r /path/to/hermes-tabular/skills/* .hermes/skills/

Add a subset the same way — but always include tabular, which is the entry point,
and the skills it will delegate to:

cp -r /path/to/hermes-tabular/skills/{tabular,tabular-inspect,tabular-load,tabular-split,tabular-baseline,tabular-catboost,tabular-evaluate} .hermes/skills/

Remove skills.

rm -rf .hermes/skills/tabular-tabicl        # drop one delegate
rm -rf .hermes/skills/tabular*              # drop the whole pack

Note the glob: tabular-* matches the nine delegates but not the tabular
orchestrator itself, leaving a stranded entry point. Use tabular* to remove
everything.

Deployment contract

Skills live at .hermes/skills/<skill-name>/, each containing a SKILL.md.
Installation is idempotent — re-copying over an existing install is a safe
update. Removal is a plain rm -rf, leaving no residue elsewhere in the project.
Skills carry no state and no imports. Nothing registers, nothing initializes,
no file outside .hermes/skills/ is touched. Adding or removing one cannot break
another.
The only cross-skill coupling is that tabular delegates by name. If a delegate
is absent, that path simply does not resolve; the other nine still work.
scripts/install_skills.py is available if you prefer it — it is idempotent and
warns about dangling delegations — but it is optional. Plain cp/rm is fewer
moving parts and one less dependency.

Then invoke exactly one skill: tabular.

The other nine are delegation targets. Do not invoke them directly; the orchestrator
decides which are needed, in what order, and reads defaults.yaml for thresholds.

Before modeling, read references/pitfalls.md. Leakage, temporal and group
leakage, preprocessing fit before splitting, and test-set reuse all produce
excellent validation numbers and worthless models. The checklist at the bottom of
that file is the fastest way to avoid shipping a confidently wrong result.

Runtime expectations

Missing optional dependency (catboost, tabicl, mapie) → report it and
continue with what is installed. Never silently skip a model family.
Skills are documentation, not a library. There is nothing to import; the reference
implementations in each SKILL.md are meant to be adapted to the dataset at hand,
not called as a fixed API.

Usage

Invoke only the orchestrator:

Use the tabular skill on data/customers.csv. Target is churned. I need
calibrated probabilities and an honest estimate of out-of-sample AUC.

tabular inspects, plans, and delegates. Everything else is an implementation
detail it calls on your behalf.

Design notes

The orchestrator holds policy, not code. skills/tabular/SKILL.md contains
almost no implementation detail. Every other skill is focused, testable, and
replaceable.
Swapability. If TabICL is superseded, only tabular-tabicl changes. The
orchestration policy stays stable.
Tunable thresholds. defaults.yaml holds the numbers so policy prose stays
stable while values evolve.
Nothing to import. The pack is Markdown. That is what makes it trivially
installable and removable by an agent, and what keeps the human's job confined to
the Python environment.
Future harnesses. Hermes is the primary supported harness. If others are ever
needed, add a thin adapters/ layer rather than renaming the project.

License

MIT. See LICENSE.

Attribution & Disclaimer

This project is an independent community package built for use with the Hermes Agent framework. It is not an official repository maintained or endorsed by Nous Research.

For the core agent framework, documentation, and official tools, visit Nous Research.

README from the reviewed commit c5b9650; it updates when the author re-pins.