bathos 0.1.0__py3-none-any.whl

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.
bathos/mcp.py ADDED
@@ -0,0 +1,500 @@
1
+ """FastMCP server for bathos experiment tracking.
2
+
3
+ Provides 10 tools that mirror the CLI:
4
+ - Query: list_runs, find_runs, get_run, run_sql
5
+ - Compact/Archive: compact, archive
6
+ - Check/Sync/Init/Run: check, sync, init, run
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import os
13
+ from pathlib import Path
14
+
15
+ from fastmcp import FastMCP
16
+
17
+ # Import core modules
18
+ from bathos.archive import archive as archive_runs
19
+ from bathos.catalog import init_catalog
20
+ from bathos.checker import check_runs
21
+ from bathos.compact import compact as compact_catalog
22
+ from bathos.config import default_catalog_dir, find_project_config, load_project_config
23
+ from bathos.init import init_project
24
+ from bathos.query import find_runs, get_run, list_runs, run_sql
25
+ from bathos.runner import run_script
26
+ from bathos.sync import sync_catalog
27
+
28
+ app = FastMCP("bathos")
29
+
30
+
31
+ def _get_catalog_dir(catalog_dir: str | None = None) -> Path:
32
+ """Resolve catalog directory from parameter or environment."""
33
+ if catalog_dir:
34
+ return Path(catalog_dir)
35
+ override = os.environ.get("BTH_CATALOG_DIR")
36
+ if override:
37
+ return Path(override)
38
+ return default_catalog_dir()
39
+
40
+
41
+ # ============================================================================
42
+ # Core tool implementations (testable functions)
43
+ # ============================================================================
44
+
45
+
46
+ def list_runs_tool(
47
+ catalog_dir: str = "",
48
+ limit: int = 10,
49
+ ) -> str:
50
+ """List recent runs from catalog.
51
+
52
+ Args:
53
+ catalog_dir: Catalog directory (empty = use default)
54
+ limit: Max runs to return (default 10)
55
+
56
+ Returns:
57
+ JSON string with runs array and count
58
+ """
59
+ try:
60
+ cat_dir = _get_catalog_dir(catalog_dir or None)
61
+ runs = list_runs(cat_dir, limit=limit)
62
+ runs_json = [
63
+ {
64
+ "id": r.id,
65
+ "project_slug": r.project_slug,
66
+ "command": r.command,
67
+ "status": r.status,
68
+ "exit_code": r.exit_code,
69
+ "duration_s": r.duration_s,
70
+ "timestamp": r.timestamp.isoformat() if r.timestamp else None,
71
+ }
72
+ for r in runs
73
+ ]
74
+ return json.dumps({"runs": runs_json, "count": len(runs_json)}, indent=2)
75
+ except Exception as e:
76
+ return json.dumps({"error": str(e)})
77
+
78
+
79
+ def find_runs_tool(
80
+ catalog_dir: str = "",
81
+ pattern: str = "",
82
+ ) -> str:
83
+ """Find runs by pattern (project, status, tag, etc).
84
+
85
+ Args:
86
+ catalog_dir: Catalog directory (empty = use default)
87
+ pattern: Filter pattern (e.g., project name)
88
+
89
+ Returns:
90
+ JSON string with matching runs
91
+ """
92
+ try:
93
+ cat_dir = _get_catalog_dir(catalog_dir or None)
94
+ # For simplicity, treat pattern as project filter
95
+ runs = find_runs(cat_dir, project=pattern if pattern else None)
96
+ runs_json = [
97
+ {
98
+ "id": r.id,
99
+ "project_slug": r.project_slug,
100
+ "command": r.command,
101
+ "status": r.status,
102
+ "exit_code": r.exit_code,
103
+ "duration_s": r.duration_s,
104
+ "timestamp": r.timestamp.isoformat() if r.timestamp else None,
105
+ }
106
+ for r in runs
107
+ ]
108
+ return json.dumps({"runs": runs_json, "count": len(runs_json)}, indent=2)
109
+ except Exception as e:
110
+ return json.dumps({"error": str(e)})
111
+
112
+
113
+ def get_run_tool(
114
+ catalog_dir: str = "",
115
+ run_id: str = "",
116
+ ) -> str:
117
+ """Get details for a specific run.
118
+
119
+ Args:
120
+ catalog_dir: Catalog directory (empty = use default)
121
+ run_id: Run ID to fetch
122
+
123
+ Returns:
124
+ JSON string with run details
125
+ """
126
+ try:
127
+ if not run_id:
128
+ return json.dumps({"error": "run_id is required"})
129
+ cat_dir = _get_catalog_dir(catalog_dir or None)
130
+ run = get_run(run_id, cat_dir)
131
+ if run is None:
132
+ return json.dumps({"error": f"Run {run_id} not found"})
133
+ run_dict = {
134
+ "id": run.id,
135
+ "project_slug": run.project_slug,
136
+ "command": run.command,
137
+ "argv": run.argv,
138
+ "git_hash": run.git_hash,
139
+ "git_branch": run.git_branch,
140
+ "git_dirty": run.git_dirty,
141
+ "status": run.status,
142
+ "exit_code": run.exit_code,
143
+ "duration_s": run.duration_s,
144
+ "timestamp": run.timestamp.isoformat() if run.timestamp else None,
145
+ "output_paths": run.output_paths,
146
+ "tags": run.tags,
147
+ "hostname": run.hostname,
148
+ }
149
+ return json.dumps(run_dict, indent=2)
150
+ except Exception as e:
151
+ return json.dumps({"error": str(e)})
152
+
153
+
154
+ def run_sql_tool(
155
+ catalog_dir: str = "",
156
+ sql: str = "",
157
+ ) -> str:
158
+ """Execute SQL query against catalog.
159
+
160
+ Args:
161
+ catalog_dir: Catalog directory (empty = use default)
162
+ sql: SQL query string
163
+
164
+ Returns:
165
+ JSON string with rows array
166
+ """
167
+ try:
168
+ if not sql:
169
+ return json.dumps({"error": "sql parameter is required"})
170
+ cat_dir = _get_catalog_dir(catalog_dir or None) if catalog_dir else None
171
+ rows = run_sql(sql, cat_dir)
172
+ rows_json = [list(row) for row in rows]
173
+ return json.dumps({"rows": rows_json, "count": len(rows_json)}, indent=2)
174
+ except Exception as e:
175
+ return json.dumps({"error": str(e)})
176
+
177
+
178
+ def compact_tool(
179
+ catalog_dir: str = "",
180
+ ) -> str:
181
+ """Compact cool-tier Parquet to warm-tier DuckDB.
182
+
183
+ Args:
184
+ catalog_dir: Catalog directory (empty = use default)
185
+
186
+ Returns:
187
+ JSON string with result summary
188
+ """
189
+ try:
190
+ cat_dir = _get_catalog_dir(catalog_dir or None)
191
+ result = compact_catalog(cat_dir)
192
+ result_dict = {
193
+ "ingested": result.ingested,
194
+ "skipped": result.skipped,
195
+ "duration_s": result.duration_s,
196
+ }
197
+ return json.dumps(result_dict, indent=2)
198
+ except Exception as e:
199
+ return json.dumps({"error": str(e)})
200
+
201
+
202
+ def archive_tool(
203
+ catalog_dir: str = "",
204
+ project: str = "",
205
+ ) -> str:
206
+ """Archive warm-tier DuckDB to cold-tier Parquet.
207
+
208
+ Args:
209
+ catalog_dir: Catalog directory (empty = use default)
210
+ project: Project slug to archive
211
+ keep_cool: Keep cool-tier Parquet after archiving
212
+
213
+ Returns:
214
+ JSON string with result summary
215
+ """
216
+ try:
217
+ if not project:
218
+ return json.dumps({"error": "project parameter is required"})
219
+ cat_dir = _get_catalog_dir(catalog_dir or None)
220
+ archive_root = cat_dir / "archive"
221
+ result = archive_runs(cat_dir, archive_root=archive_root, project_slug=project)
222
+ result_dict = {
223
+ "runs_archived": result.runs_archived,
224
+ "partitions_created": result.partitions_created,
225
+ "archive_size_bytes": result.archive_size_bytes,
226
+ "duration_s": result.duration_s,
227
+ }
228
+ return json.dumps(result_dict, indent=2)
229
+ except Exception as e:
230
+ return json.dumps({"error": str(e)})
231
+
232
+
233
+ def check_tool(
234
+ catalog_dir: str = "",
235
+ project_root: str = "",
236
+ status_filter: str = "",
237
+ ) -> str:
238
+ """Check run freshness vs git HEAD.
239
+
240
+ Args:
241
+ catalog_dir: Catalog directory (empty = use default)
242
+ project_root: Project root directory (empty = current directory)
243
+ status_filter: Filter by status (e.g., "stale")
244
+
245
+ Returns:
246
+ JSON string with check results
247
+ """
248
+ try:
249
+ cat_dir = _get_catalog_dir(catalog_dir or None)
250
+ proj_root = Path(project_root) if project_root else Path.cwd()
251
+ results = check_runs(cat_dir, proj_root, status_filter=status_filter)
252
+ results_json = [
253
+ {
254
+ "run_id": r.run_id,
255
+ "status": r.status,
256
+ }
257
+ for r in results
258
+ ]
259
+ return json.dumps({"results": results_json, "count": len(results_json)}, indent=2)
260
+ except Exception as e:
261
+ return json.dumps({"error": str(e)})
262
+
263
+
264
+ def sync_tool(
265
+ catalog_dir: str = "",
266
+ remote_name: str = "",
267
+ pull: bool = False,
268
+ ) -> str:
269
+ """Sync catalog to/from remote.
270
+
271
+ Args:
272
+ catalog_dir: Catalog directory (empty = use default)
273
+ remote_name: Remote name from .bth.toml
274
+ pull: Pull from remote (default: push to remote)
275
+
276
+ Returns:
277
+ JSON string with sync result
278
+ """
279
+ try:
280
+ if not remote_name:
281
+ return json.dumps({"error": "remote_name parameter is required"})
282
+ cat_dir = _get_catalog_dir(catalog_dir or None)
283
+ # Load ProjectConfig from .bth.toml in project root
284
+ config_path = find_project_config(Path.cwd())
285
+ if not config_path:
286
+ return json.dumps({"error": "Could not find .bth.toml in project hierarchy"})
287
+ config = load_project_config(config_path)
288
+ result = sync_catalog(remote_name, config, cat_dir, pull=pull)
289
+ result_dict = {
290
+ "transferred": result.transferred,
291
+ "duration_s": result.duration_s,
292
+ "remote": result.remote,
293
+ }
294
+ return json.dumps(result_dict, indent=2)
295
+ except Exception as e:
296
+ return json.dumps({"error": str(e)})
297
+
298
+
299
+ def init_tool(
300
+ project_root: str = "",
301
+ catalog_dir: str = "",
302
+ slug: str = "",
303
+ remote: str = "",
304
+ slurm_partition: str = "",
305
+ ) -> str:
306
+ """Initialize project with bathos.
307
+
308
+ Args:
309
+ project_root: Project root directory (empty = current directory)
310
+ catalog_dir: Catalog directory (empty = use default)
311
+ slug: Project slug
312
+ remote: Remote in host:path format
313
+ slurm_partition: Default SLURM partition
314
+
315
+ Returns:
316
+ JSON string with init result
317
+ """
318
+ try:
319
+ if not slug:
320
+ return json.dumps({"error": "slug parameter is required"})
321
+ root = Path(project_root) if project_root else Path.cwd()
322
+ cat_dir = _get_catalog_dir(catalog_dir or None)
323
+ init_project(
324
+ root,
325
+ slug=slug,
326
+ catalog_dir=cat_dir,
327
+ remote=remote or None,
328
+ slurm_partition=slurm_partition or None,
329
+ )
330
+ init_catalog(cat_dir)
331
+ return json.dumps(
332
+ {
333
+ "initialized": True,
334
+ "catalog_dir": str(cat_dir),
335
+ "project_root": str(root),
336
+ "slug": slug,
337
+ },
338
+ indent=2,
339
+ )
340
+ except Exception as e:
341
+ return json.dumps({"error": str(e)})
342
+
343
+
344
+ def run_tool(
345
+ script_path: str = "",
346
+ args: list[str] | None = None,
347
+ ) -> str:
348
+ """Run a script and record provenance.
349
+
350
+ Args:
351
+ script_path: Path to script
352
+ args: Command-line arguments
353
+
354
+ Returns:
355
+ JSON string with run result
356
+ """
357
+ try:
358
+ if not script_path:
359
+ return json.dumps({"error": "script_path parameter is required"})
360
+ if args is None:
361
+ args = []
362
+ # Construct argv: ['python', script_path, ...args]
363
+ argv = ["python", script_path] + args
364
+ exit_code = run_script(
365
+ argv=argv,
366
+ project_slug="default",
367
+ catalog_dir=_get_catalog_dir(None),
368
+ output_paths=[],
369
+ tags=[],
370
+ )
371
+ return json.dumps(
372
+ {
373
+ "script_path": script_path,
374
+ "exit_code": exit_code,
375
+ "success": exit_code == 0,
376
+ },
377
+ indent=2,
378
+ )
379
+ except Exception as e:
380
+ return json.dumps({"error": str(e)})
381
+
382
+
383
+ # ============================================================================
384
+ # MCP server tool registrations
385
+ # ============================================================================
386
+
387
+
388
+ @app.tool("list_runs")
389
+ def mcp_list_runs_tool(
390
+ catalog_dir: str = "",
391
+ limit: int = 10,
392
+ ) -> str:
393
+ """List recent runs from catalog."""
394
+ return list_runs_tool(catalog_dir=catalog_dir, limit=limit)
395
+
396
+
397
+ @app.tool("find_runs")
398
+ def mcp_find_runs_tool(
399
+ catalog_dir: str = "",
400
+ pattern: str = "",
401
+ ) -> str:
402
+ """Find runs by pattern."""
403
+ return find_runs_tool(catalog_dir=catalog_dir, pattern=pattern)
404
+
405
+
406
+ @app.tool("get_run")
407
+ def mcp_get_run_tool(
408
+ catalog_dir: str = "",
409
+ run_id: str = "",
410
+ ) -> str:
411
+ """Get details for a specific run."""
412
+ return get_run_tool(catalog_dir=catalog_dir, run_id=run_id)
413
+
414
+
415
+ @app.tool("run_sql")
416
+ def mcp_run_sql_tool(
417
+ catalog_dir: str = "",
418
+ sql: str = "",
419
+ ) -> str:
420
+ """Execute SQL query against catalog."""
421
+ return run_sql_tool(catalog_dir=catalog_dir, sql=sql)
422
+
423
+
424
+ @app.tool("compact")
425
+ def mcp_compact_tool(
426
+ catalog_dir: str = "",
427
+ ) -> str:
428
+ """Compact cool-tier Parquet to warm-tier DuckDB."""
429
+ return compact_tool(catalog_dir=catalog_dir)
430
+
431
+
432
+ @app.tool("archive")
433
+ def mcp_archive_tool(
434
+ catalog_dir: str = "",
435
+ project: str = "",
436
+ keep_cool: bool = False,
437
+ ) -> str:
438
+ """Archive warm-tier DuckDB to cold-tier Parquet."""
439
+ return archive_tool(catalog_dir=catalog_dir, project=project, keep_cool=keep_cool)
440
+
441
+
442
+ @app.tool("check")
443
+ def mcp_check_tool(
444
+ catalog_dir: str = "",
445
+ project_root: str = "",
446
+ status_filter: str = "",
447
+ ) -> str:
448
+ """Check run freshness vs git HEAD."""
449
+ return check_tool(
450
+ catalog_dir=catalog_dir, project_root=project_root, status_filter=status_filter
451
+ )
452
+
453
+
454
+ @app.tool("sync")
455
+ def mcp_sync_tool(
456
+ catalog_dir: str = "",
457
+ remote_name: str = "",
458
+ pull: bool = False,
459
+ ) -> str:
460
+ """Sync catalog to/from remote."""
461
+ return sync_tool(catalog_dir=catalog_dir, remote_name=remote_name, pull=pull)
462
+
463
+
464
+ @app.tool("init")
465
+ def mcp_init_tool(
466
+ project_root: str = "",
467
+ catalog_dir: str = "",
468
+ slug: str = "",
469
+ remote: str = "",
470
+ slurm_partition: str = "",
471
+ ) -> str:
472
+ """Initialize project with bathos."""
473
+ return init_tool(
474
+ project_root=project_root,
475
+ catalog_dir=catalog_dir,
476
+ slug=slug,
477
+ remote=remote,
478
+ slurm_partition=slurm_partition,
479
+ )
480
+
481
+
482
+ @app.tool("run")
483
+ def mcp_run_tool(
484
+ script_path: str = "",
485
+ args: list[str] | None = None,
486
+ ) -> str:
487
+ """Run a script and record provenance."""
488
+ return run_tool(script_path=script_path, args=args)
489
+
490
+
491
+ def mcp_server():
492
+ """Entry point for MCP server (stdio transport).
493
+
494
+ Called by pyproject.toml entry point: bth-mcp
495
+ """
496
+ app.run()
497
+
498
+
499
+ if __name__ == "__main__":
500
+ app.run()