bathos 0.1.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. bathos-0.3.0/.bth.toml +7 -0
  2. bathos-0.3.0/CHANGELOG.md +172 -0
  3. {bathos-0.1.0 → bathos-0.3.0}/PKG-INFO +5 -1
  4. {bathos-0.1.0 → bathos-0.3.0}/README.md +2 -0
  5. bathos-0.3.0/agent_assets/docs/claude-code-integration.md +56 -0
  6. bathos-0.3.0/agent_assets/docs/gemini-cli-integration.md +56 -0
  7. bathos-0.3.0/agent_assets/using_bathos/SKILL.md +1063 -0
  8. bathos-0.3.0/docs/superpowers/plans/2026-05-19-agent-onboarding-export.md +500 -0
  9. bathos-0.3.0/docs/superpowers/plans/2026-05-19-decorator.md +328 -0
  10. bathos-0.3.0/docs/superpowers/plans/2026-05-19-historical-migration.md +355 -0
  11. bathos-0.3.0/docs/superpowers/plans/2026-05-19-linter.md +416 -0
  12. bathos-0.3.0/docs/superpowers/plans/2026-05-19-remote-management.md +386 -0
  13. bathos-0.3.0/docs/superpowers/plans/2026-05-19-schema-versioning.md +375 -0
  14. bathos-0.3.0/docs/superpowers/plans/2026-05-19-skill-and-export-mcp.md +364 -0
  15. bathos-0.3.0/docs/superpowers/plans/2026-05-19-v02-feature-wiring.md +857 -0
  16. bathos-0.3.0/docs/superpowers/plans/2026-05-20-agentic-integrity-design.md +328 -0
  17. bathos-0.3.0/docs/superpowers/plans/2026-05-20-agentic-integrity-impl-plan.md +2146 -0
  18. bathos-0.3.0/inventory.txt +8 -0
  19. {bathos-0.1.0 → bathos-0.3.0}/pyproject.toml +6 -1
  20. bathos-0.3.0/scripts/benchmarks/.bth.toml +12 -0
  21. bathos-0.3.0/scripts/experiments/.bth.toml +18 -0
  22. bathos-0.3.0/scripts/slurm/_bth_env.sh +6 -0
  23. bathos-0.3.0/src/bathos/__init__.py +5 -0
  24. bathos-0.3.0/src/bathos/campaigns.py +161 -0
  25. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/catalog.py +1 -1
  26. bathos-0.3.0/src/bathos/cli.py +777 -0
  27. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/compact.py +103 -7
  28. bathos-0.3.0/src/bathos/config.py +70 -0
  29. bathos-0.3.0/src/bathos/decorators.py +73 -0
  30. bathos-0.3.0/src/bathos/export.py +143 -0
  31. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/init.py +5 -0
  32. bathos-0.3.0/src/bathos/linter.py +338 -0
  33. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/mcp.py +331 -6
  34. bathos-0.3.0/src/bathos/migrate.py +78 -0
  35. bathos-0.3.0/src/bathos/new_experiment.py +82 -0
  36. bathos-0.3.0/src/bathos/prereg.py +160 -0
  37. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/query.py +61 -1
  38. bathos-0.3.0/src/bathos/remote.py +172 -0
  39. bathos-0.3.0/src/bathos/runner.py +240 -0
  40. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/schema.py +47 -1
  41. bathos-0.3.0/src/bathos/sidecar.py +162 -0
  42. bathos-0.3.0/src/bathos/sprint_audit.py +128 -0
  43. bathos-0.3.0/src/bathos/validate.py +126 -0
  44. bathos-0.3.0/tests/test_campaigns.py +273 -0
  45. {bathos-0.1.0 → bathos-0.3.0}/tests/test_cli.py +42 -1
  46. {bathos-0.1.0 → bathos-0.3.0}/tests/test_compact.py +132 -19
  47. bathos-0.3.0/tests/test_decorators.py +107 -0
  48. bathos-0.3.0/tests/test_export.py +126 -0
  49. {bathos-0.1.0 → bathos-0.3.0}/tests/test_integration.py +2 -2
  50. bathos-0.3.0/tests/test_linter.py +203 -0
  51. bathos-0.3.0/tests/test_migrate.py +134 -0
  52. bathos-0.3.0/tests/test_new_experiment.py +70 -0
  53. bathos-0.3.0/tests/test_prereg.py +254 -0
  54. {bathos-0.1.0 → bathos-0.3.0}/tests/test_query.py +90 -0
  55. bathos-0.3.0/tests/test_remote.py +656 -0
  56. bathos-0.3.0/tests/test_runner.py +480 -0
  57. {bathos-0.1.0 → bathos-0.3.0}/tests/test_schema.py +109 -6
  58. bathos-0.3.0/tests/test_sidecar.py +204 -0
  59. bathos-0.3.0/tests/test_sprint_audit.py +125 -0
  60. bathos-0.3.0/tests/test_validate.py +264 -0
  61. {bathos-0.1.0 → bathos-0.3.0}/uv.lock +23 -1
  62. bathos-0.1.0/.bth.toml +0 -3
  63. bathos-0.1.0/CHANGELOG.md +0 -111
  64. bathos-0.1.0/src/bathos/__init__.py +0 -1
  65. bathos-0.1.0/src/bathos/cli.py +0 -337
  66. bathos-0.1.0/src/bathos/config.py +0 -37
  67. bathos-0.1.0/src/bathos/runner.py +0 -53
  68. bathos-0.1.0/tests/test_runner.py +0 -92
  69. {bathos-0.1.0 → bathos-0.3.0}/.agent/workspace.id +0 -0
  70. {bathos-0.1.0 → bathos-0.3.0}/.coverage +0 -0
  71. {bathos-0.1.0 → bathos-0.3.0}/.github/SECRETS.md +0 -0
  72. {bathos-0.1.0 → bathos-0.3.0}/.github/workflows/publish.yml +0 -0
  73. {bathos-0.1.0 → bathos-0.3.0}/.github/workflows/test.yml +0 -0
  74. {bathos-0.1.0 → bathos-0.3.0}/.gitignore +0 -0
  75. {bathos-0.1.0 → bathos-0.3.0}/.python-version +0 -0
  76. /bathos-0.1.0/.readthedocs.yml → /bathos-0.3.0/.readthedocs.yaml +0 -0
  77. {bathos-0.1.0 → bathos-0.3.0}/CLAUDE.md +0 -0
  78. {bathos-0.1.0 → bathos-0.3.0}/LICENSE +0 -0
  79. {bathos-0.1.0 → bathos-0.3.0}/docs/Makefile +0 -0
  80. {bathos-0.1.0 → bathos-0.3.0}/docs/source/api.rst +0 -0
  81. {bathos-0.1.0 → bathos-0.3.0}/docs/source/architecture.rst +0 -0
  82. {bathos-0.1.0 → bathos-0.3.0}/docs/source/conf.py +0 -0
  83. {bathos-0.1.0 → bathos-0.3.0}/docs/source/contributing.rst +0 -0
  84. {bathos-0.1.0 → bathos-0.3.0}/docs/source/index.rst +0 -0
  85. {bathos-0.1.0 → bathos-0.3.0}/docs/source/slurm-integration.rst +0 -0
  86. {bathos-0.1.0 → bathos-0.3.0}/docs/source/user-guide.rst +0 -0
  87. {bathos-0.1.0 → bathos-0.3.0}/docs/superpowers/plans/2026-05-15-bathos-v01-core.md +0 -0
  88. {bathos-0.1.0 → bathos-0.3.0}/docs/superpowers/specs/2026-05-15-bathos-design.md +0 -0
  89. {bathos-0.1.0 → bathos-0.3.0}/main.py +0 -0
  90. {bathos-0.1.0 → bathos-0.3.0}/praxia.toml +0 -0
  91. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/archive.py +0 -0
  92. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/checker.py +0 -0
  93. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/git.py +0 -0
  94. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/sync.py +0 -0
  95. {bathos-0.1.0 → bathos-0.3.0}/src/bathos/templates/_bth_env.sh +0 -0
  96. {bathos-0.1.0 → bathos-0.3.0}/tests/__init__.py +0 -0
  97. {bathos-0.1.0 → bathos-0.3.0}/tests/conftest.py +0 -0
  98. {bathos-0.1.0 → bathos-0.3.0}/tests/test_archive.py +0 -0
  99. {bathos-0.1.0 → bathos-0.3.0}/tests/test_catalog.py +0 -0
  100. {bathos-0.1.0 → bathos-0.3.0}/tests/test_checker.py +0 -0
  101. {bathos-0.1.0 → bathos-0.3.0}/tests/test_cluster_workflow.py +0 -0
  102. {bathos-0.1.0 → bathos-0.3.0}/tests/test_config.py +0 -0
  103. {bathos-0.1.0 → bathos-0.3.0}/tests/test_git.py +0 -0
  104. {bathos-0.1.0 → bathos-0.3.0}/tests/test_init.py +0 -0
  105. {bathos-0.1.0 → bathos-0.3.0}/tests/test_mcp_integration.py +0 -0
  106. {bathos-0.1.0 → bathos-0.3.0}/tests/test_mcp_server.py +0 -0
  107. {bathos-0.1.0 → bathos-0.3.0}/tests/test_slurm_integration.py +0 -0
  108. {bathos-0.1.0 → bathos-0.3.0}/tests/test_sync.py +0 -0
bathos-0.3.0/.bth.toml ADDED
@@ -0,0 +1,7 @@
1
+ [project]
2
+ slug = "prolix"
3
+ root = "/home/marielle/projects/bathos"
4
+
5
+ [remotes.engaging]
6
+ host = "engaging"
7
+ remote_root = "~/projects/prolix"
@@ -0,0 +1,172 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.3.0] - 2026-05-20
9
+
10
+ ### Added
11
+
12
+ - **Agentic integrity gate layer** — `prereg.py` enforces sidecar presence and structural validity before any run in `scripts/experiments/`, `scripts/benchmarks/`, or `scripts/validation/`; structured JSON gate errors returned on failure with `gate_schema_version: 1`, `errors[]`, and `remediation` guidance
13
+ - **Run modes: collaborative / autonomous** — `bth run --agent-mode <mode>`; priority chain: CLI flag → sidecar `[experiment] agent_mode` → project `.bth.toml` `[defaults]` → global config → `"collaborative"`; autonomous mode enforces first-of-kind check (blocks re-running the same script at the same git HEAD)
14
+ - **Sidecar structural validator** (`validate.py`) — checks `[outcomes.*]` blocks for `condition`, `decision`, `reasoning` fields; validates DuckDB SQL conditions; requires at least one `is_residual = true` fallback branch; requires at least one `result_schema` field referenced in conditions
15
+ - **Schema v3** — 8 new fields on `Run`: `sidecar_sha256`, `sidecar_path`, `parent_run_id`, `agent_mode`, `sidecar_mode`, `outcome_is_residual`, `skill_sha256`, `campaign_id`; full migration chain v0→v1→v2→v3
16
+ - **Result emission pipeline** — `$BTH_RESULTS_PATH` env var (or `<stem>.bth-results.json` fallback) connects script output to outcome evaluation; `run.outcome` now populated from sidecar conditions at run-end
17
+ - **Lineage tracking** — `bth run --derived-from <run-id>` links runs into a DAG; `bth lineage <run-id>` shows ancestor chain via recursive CTE with cycle protection
18
+ - **Campaigns** — `bth campaign create/add/conclude/ls/show/review`; two modes: `exploration` (no temporal constraint) and `confirmation` (enforces runs must postdate campaign creation); campaign membership written to cool fragment at run time and auto-populated to warm `campaign_runs` table at compaction
19
+ - **Sprint audit** — `bth sprint-audit [--hours N]` cross-project audit across all registered projects; skips projects with incompatible schema version with warning; detects unknown outcomes, bypass spikes, residual rate anomalies
20
+ - **Tier-2 lint checks** (`bth lint` extended) — `check_residual_rates` (warn >10% per campaign), `check_bypass_trend` (warn if bypass rate increasing week-over-week), `check_unfired_branches` (warn if all runs in a group map to same outcome)
21
+ - **MCP campaign tools** — `campaign_create`, `campaign_list`, `campaign_review`, `campaign_conclude` exposed as MCP tools; `run` tool extended with `agent_mode`, `campaign_id`, `derived_from`, `no_sidecar` parameters; gate failures returned as structured tool results
22
+ - **CLI flags** — `bth run --agent-mode`, `--no-sidecar`, `--derived-from`, `--campaign`; `bth ls --outcome`, `--sidecar-mode`
23
+ - **SKILL.md agentic integrity section** — three-tier taxonomy (Tier 1: validate, Tier 2: lint, Tier 3: principles) + campaign workflow examples
24
+
25
+ ### Fixed
26
+
27
+ - `compact.py` — outcome labels from cool fragments now preserved during warm-tier promotion (previously silently set to NULL)
28
+ - `prereg.py` — `check_first_of_kind()` SQL query now parameterised (previously used f-string interpolation, SQL injection risk)
29
+ - `compact.py` — `_migrate_v1()` now hardcodes target version `"2"` (previously referenced `CURRENT_SCHEMA_VERSION` dynamically, which would cause v1→v3 skip when version bumped)
30
+ - `query.py` — `lineage()` CTE now handles NULL `parent_run_id` via `COALESCE` and guards against cycles with `depth < 50` limit
31
+ - `campaigns.py` — temporal ordering comparison now uses parsed datetimes with timezone normalisation (previously compared heterogeneous types as strings)
32
+
33
+ ---
34
+
35
+ ## [0.2.1] - 2026-05-19
36
+
37
+ ### Fixed
38
+
39
+ - **Skill export** — skill is now written as `using-bathos/SKILL.md` (directory format) with proper YAML frontmatter, matching the Claude Code skill loader convention; previously exported as a flat `.md` file with no frontmatter
40
+ - **Version stamp placement** — HTML version comment is now inserted after the frontmatter closing `---` rather than before it, so frontmatter parsers see clean YAML
41
+ - **Wheel packaging** — `agent_assets/` is now bundled into the wheel via `force-include`, so `bth export` works from an installed (non-editable) copy
42
+
43
+ ### Added
44
+
45
+ - **Public alpha notice** — README now prominently notes that bathos is experimental, WIP, and should be treated as a public alpha
46
+
47
+ ---
48
+
49
+ ## [0.2.0] - 2026-05-19
50
+
51
+ ### Added
52
+
53
+ - **`bth remote`** — new subcommand group for managing sync remotes
54
+ - `bth remote add <name> <host:path>` — add a remote, written to `.bth.toml` via `tomlkit` (preserves comments and formatting)
55
+ - `bth remote list` — tabular display of configured remotes
56
+ - `bth remote remove <name>` — remove a remote, cleans up empty `[remotes]` section
57
+ - `bth remote test <name>` — SSH connectivity check with latency measurement
58
+ - **`bth sync` optional remote** — remote argument is now optional; auto-selected when exactly one remote is configured, error with names listed when multiple are present
59
+ - **`@bth.experiment` decorator** — provenance-capturing decorator for Typer-based scripts; records git state, timing, exit code, and output paths without modifying script behaviour
60
+ - **`bth lint`** — naming convention and sidecar enforcement checker across all `scripts/` subdirectories
61
+ - **`bth new-experiment`** — scaffolds a new experiment script and companion sidecar in `scripts/experiments/`
62
+ - **`bth migrate`** — upgrades cool-tier Parquet fragments to current schema without data loss
63
+ - **`bth catalog-version`** — reports current schema version and migration status of cool and warm tiers
64
+ - **`bth export`** — exports the `using-bathos` Claude Code / Gemini skill and registers the MCP server in the tool's config file (`~/.claude.json` for Claude Code user level)
65
+ - **Schema versioning** — `CURRENT_SCHEMA_VERSION` constant centralised in `schema.py`; `_schema_migrations` audit table written on every `bth compact`
66
+
67
+ ---
68
+
69
+ ## [0.1.0] - 2026-05-18
70
+
71
+ ### Added
72
+
73
+ #### Core CLI Commands (v0.1 feature-complete)
74
+
75
+ - **`bth init`** — Initialize experiment tracking in a project directory
76
+ - Creates script subdirectories with required structure
77
+ - Generates `.bth.toml` project configuration
78
+ - Exports `_bth_env.sh` for SLURM integration
79
+ - Sets up `.gitignore` for catalog and cache directories
80
+
81
+ - **`bth run`** — Execute a tracked script with automatic provenance capture
82
+ - Wraps script execution with subprocess isolation
83
+ - Captures git state (repo, HEAD SHA, dirty flag)
84
+ - Records SLURM job context when available
85
+ - Writes atomic Parquet fragments to cool-tier catalog
86
+ - Supports environment variable overrides
87
+
88
+ - **`bth ls`** — List recent experiment runs with rich formatting
89
+ - Displays run metadata (timestamp, script, git SHA, outcome)
90
+ - Filters by script directory or project slug
91
+ - Shows active/failed runs with visual indicators
92
+ - Banner displays catalog path and warm DB status
93
+
94
+ - **`bth show`** — Display detailed metadata for a specific run
95
+ - Prints all provenance fields (git state, SLURM context, timing)
96
+ - Shows result schema fields and outcome label
97
+ - Expands metadata JSON for human-readable inspection
98
+
99
+ - **`bth find`** — Query runs with SQL-like filtering
100
+ - Filter by script name, git SHA, outcome, or custom fields
101
+ - Output format options: table (default), json, parquet
102
+ - Optional `--output-file` parameter for file-level filtering
103
+ - Uses DuckDB backend (warm DB or cool-tier Parquet scan)
104
+
105
+ - **`bth sql`** — Execute arbitrary SQL against the catalog
106
+ - Queries both cool-tier (Parquet fragments) and warm-tier (DuckDB)
107
+ - Returns results in json, table, or parquet format
108
+ - Error messaging for missing warm DB with remediation hint
109
+
110
+ #### Tiered Storage & Compaction
111
+
112
+ - **Cool tier** — Per-run atomic Parquet files
113
+ - SLURM-safe parallel writes via write-then-rename
114
+ - Minimal schema: 13 provenance fields + result JSON column
115
+ - Files located at `~/.bth/catalog/runs/run_<uuid>.parquet`
116
+
117
+ - **Warm tier** — DuckDB database for interactive queries
118
+ - **`bth compact`** — Ingest cool→warm with schema migrations
119
+ - Executes in background or foreground
120
+ - Fragment count reporting and caching
121
+
122
+ - **Schema versioning** — v1→v2 migration with chaining
123
+ - v1: core provenance fields
124
+ - v2: adds hostname field (defaults to `socket.gethostname()`)
125
+ - **`bth check`** — Validate run git-drift and schema freshness
126
+ - Reports stale runs vs current HEAD
127
+ - Supports `--check-outputs` for file-level verification
128
+
129
+ #### Archive & Cleanup
130
+
131
+ - **`bth archive`** — Export warm→cold partitioned Parquet
132
+ - Partitions by project, year, month for historical bulk export
133
+ - Supports `--dry-run` for preview
134
+ - Ready for cluster remote archival
135
+
136
+ #### Extended Metadata
137
+
138
+ - **Hostname capture** — Tracks execution machine
139
+ - **SLURM integration** — Records job ID, partition, node when available
140
+ - **Outcome column** — Pre-registration outcome labels at run-end
141
+ - **Output metadata** — File-level tracking during `bth compact`
142
+
143
+ ### Architecture
144
+
145
+ - **Stack**: Python 3.12, Typer, DuckDB, PyArrow, Parquet
146
+ - **Entry points**: `bth` (CLI), `bth-mcp` (FastMCP server, optional)
147
+ - **Tests**: 44 passing tests covering all CLI commands, schema migrations, and integration
148
+
149
+ ### Documentation
150
+
151
+ - Comprehensive `pyproject.toml` with classifiers, URLs, and entry points
152
+ - Apache 2.0 LICENSE file with copyright notice
153
+ - README with quick-start guide and architecture overview
154
+
155
+ ---
156
+
157
+ ## Notes
158
+
159
+ **What's not in v0.1:**
160
+ - FastMCP server (planned for v0.2)
161
+ - Sidecar pre-registration enforcement
162
+ - Global instruction portability
163
+ - Frontmatter support (planned for v0.2)
164
+
165
+ **Backlog (v0.2 candidates):**
166
+ - #128: FastMCP server implementation
167
+ - #131: Enhanced SLURM integration
168
+ - #132: `bth new-experiment` scaffold command
169
+ - #133: PyPI release & RTD setup
170
+ - #135–142: Schema versioning, results management, archive tier
171
+
172
+ See `.praxia/specs/bathos-design.md` and project backlog for full roadmap.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: bathos
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Local-first, zero-server experiment tracking for researchers
5
5
  Project-URL: Homepage, https://github.com/mariellerossi/bathos
6
6
  Project-URL: Documentation, https://bathos.readthedocs.io
@@ -21,6 +21,8 @@ Requires-Python: >=3.12
21
21
  Requires-Dist: duckdb>=1.0
22
22
  Requires-Dist: pyarrow>=16
23
23
  Requires-Dist: pytz>=2026.2
24
+ Requires-Dist: toml>=0.10
25
+ Requires-Dist: tomlkit>=0.12
24
26
  Requires-Dist: typer>=0.12
25
27
  Provides-Extra: dev
26
28
  Requires-Dist: pyright>=1.1; extra == 'dev'
@@ -39,6 +41,8 @@ Description-Content-Type: text/markdown
39
41
  [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mariellerossi/bathos/blob/main/LICENSE)
40
42
  [![Documentation](https://img.shields.io/readthedocs/bathos.svg)](https://bathos.readthedocs.io)
41
43
 
44
+ > **Public alpha — experimental software.** bathos is under active development and should be considered a work in progress. APIs, catalog schema, and CLI commands may change between releases without a deprecation period. It is used in production by the author, but expect rough edges and missing features. Feedback and bug reports welcome.
45
+
42
46
  Local-first, zero-server experiment tracking for researchers working across multiple projects and SLURM clusters.
43
47
 
44
48
  Never lose track of what ran, what it produced, or whether results are still valid.
@@ -5,6 +5,8 @@
5
5
  [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mariellerossi/bathos/blob/main/LICENSE)
6
6
  [![Documentation](https://img.shields.io/readthedocs/bathos.svg)](https://bathos.readthedocs.io)
7
7
 
8
+ > **Public alpha — experimental software.** bathos is under active development and should be considered a work in progress. APIs, catalog schema, and CLI commands may change between releases without a deprecation period. It is used in production by the author, but expect rough edges and missing features. Feedback and bug reports welcome.
9
+
8
10
  Local-first, zero-server experiment tracking for researchers working across multiple projects and SLURM clusters.
9
11
 
10
12
  Never lose track of what ran, what it produced, or whether results are still valid.
@@ -0,0 +1,56 @@
1
+ # bathos Integration — Claude Code
2
+
3
+ bathos provides a skill (`using-bathos`) that teaches Claude Code how to:
4
+ - Track experiments via `bth run`
5
+ - Query results via `bth ls`, `bth find`, `bth sql`
6
+ - Validate runs via `bth check` _(coming in v0.2 — not yet available)_
7
+ - Decide when to dispatch vs. run CLI directly
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ # User-level (available in all projects)
13
+ bth export --tool claude --level user
14
+
15
+ # Workspace-level (current project only)
16
+ bth export --tool claude --level workspace
17
+ ```
18
+
19
+ This writes `using-bathos.md` to `~/.claude/skills/` or `.claude/skills/` respectively.
20
+
21
+ ## Verify
22
+
23
+ ```bash
24
+ ls ~/.claude/skills/using-bathos.md
25
+ ```
26
+
27
+ The skill is loaded automatically at session start in Claude Code. In a new session, the agent will have bathos commands available in its routing table.
28
+
29
+ ## What the skill teaches agents
30
+
31
+ - **When to call `bth run`** vs. executing scripts directly
32
+ - **How to create sidecars** (`.bth.toml`) for pre-registration
33
+ - **Outcome evaluation** — how `bth ls` OUTCOME column maps to pass/marginal/fail
34
+ - **SLURM integration** — using `_bth_env.sh` in batch scripts
35
+ - **Cross-project queries** — `bth sql` across all projects
36
+
37
+ ## MCP tool reference (if FastMCP is enabled)
38
+
39
+ | MCP Tool | CLI equivalent | Status |
40
+ |----------|---------------|--------|
41
+ | `run_script` | `bth run` | ✅ Available |
42
+ | `list_runs` | `bth ls` | ✅ Available |
43
+ | `get_run` | `bth show <id>` | ✅ Available |
44
+ | `find_runs` | `bth find` | ✅ Available |
45
+ | `run_sql` | `bth sql` | ✅ Available |
46
+ | `compact_catalog` | `bth compact` | ✅ Available |
47
+ | `check_runs` | `bth check` | 🔜 Coming in v0.2 |
48
+ | `archive_runs` | `bth archive` | 🔜 Coming in v0.2 |
49
+
50
+ ## Update
51
+
52
+ ```bash
53
+ bth export --tool claude --level user
54
+ ```
55
+
56
+ Re-running overwrites with the latest skill version (stamped with bathos version and timestamp in first line).
@@ -0,0 +1,56 @@
1
+ # bathos Integration — Gemini CLI
2
+
3
+ bathos provides a skill (`using-bathos`) that teaches Gemini CLI how to:
4
+ - Track experiments via `bth run`
5
+ - Query results via `bth ls`, `bth find`, `bth sql`
6
+ - Validate runs via `bth check` _(coming in v0.2 — not yet available)_
7
+ - Decide when to dispatch vs. run CLI directly
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ # User-level (available in all projects)
13
+ bth export --tool gemini --level user
14
+
15
+ # Workspace-level (current project only)
16
+ bth export --tool gemini --level workspace
17
+ ```
18
+
19
+ This writes `using-bathos.md` to `~/.gemini/skills/` or `.gemini/skills/` respectively.
20
+
21
+ ## Verify
22
+
23
+ ```bash
24
+ ls ~/.gemini/skills/using-bathos.md
25
+ ```
26
+
27
+ Gemini CLI loads skills from these paths at session start via its skill discovery mechanism.
28
+
29
+ ## What the skill teaches agents
30
+
31
+ - **When to call `bth run`** vs. executing scripts directly
32
+ - **How to create sidecars** (`.bth.toml`) for pre-registration
33
+ - **Outcome evaluation** — how `bth ls` OUTCOME column maps to pass/marginal/fail
34
+ - **SLURM integration** — using `_bth_env.sh` in batch scripts
35
+ - **Cross-project queries** — `bth sql` across all projects
36
+
37
+ ## Tool name mapping
38
+
39
+ Gemini CLI tools use different names from Claude Code. The using-bathos skill is written for Claude Code tool names. For Gemini CLI, the following equivalents apply:
40
+
41
+ | Skill tool name | Gemini CLI equivalent |
42
+ |-----------------|-----------------------|
43
+ | `Bash` | `run_shell_command` |
44
+ | `Read` | `read_file` |
45
+ | `Edit` | `replace_in_file` |
46
+ | `Write` | `write_file` |
47
+
48
+ The SKILL.md uses Claude Code names; adapt accordingly when the Gemini CLI skill loader doesn't auto-translate.
49
+
50
+ ## Update
51
+
52
+ ```bash
53
+ bth export --tool gemini --level user
54
+ ```
55
+
56
+ Re-running overwrites with the latest skill version.