Robot Guidance by aritraghsh09 · Pull Request #635 · lincc-frameworks/hyrax

aritraghsh09 · 2026-01-27T19:03:19Z

Based on our last discussion, I am opening this initial PR to get our robot guidance into the repository.

I have put an initial CLAUDE.md
- SEs: Please feel free to completely change this and especially add specific guidance on code style and other things. Some links on how to edit/tune a CLAUDE.md : Anthropic Recs. Humanlayer Blog.
- Feel free to directly push changes to this branch
Please free to add similar .md files for other tools we are using -- maybe CoPilot has a similar guidance system

codecov · 2026-01-27T19:09:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.44%. Comparing base (5ce3d93) to head (a29477e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #635   +/-   ##
=======================================
  Coverage   62.44%   62.44%           
=======================================
  Files          53       53           
  Lines        5275     5275           
=======================================
  Hits         3294     3294           
  Misses       1981     1981

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-01-27T19:41:22Z

Before [`5ce3d93`]	After [`9bee6f8`]	Ratio	Benchmark (Parameter)
2.77±0.1s	3.37±0.1s	~1.22	vector_db_benchmarks.VectorDBInsertBenchmarks.time_load_vector_db(64, 'qdrant')
3.68±0.3s	3.76±0.06s	1.02	vector_db_benchmarks.VectorDBInsertBenchmarks.time_load_vector_db(256, 'qdrant')
8.31±0.1ms	8.52±0.04ms	1.02	vector_db_benchmarks.VectorDBSearchBenchmarks.time_search_by_vector_many_shards(128, 'chromadb')
1.73±0.01s	1.76±0.02s	1.01	benchmarks.time_database_connection_help
1.72±0.01s	1.73±0.02s	1.01	benchmarks.time_train_help
1.73±0.02s	1.75±0.01s	1.01	benchmarks.time_umap_help
7.24±0.05s	7.30±0.05s	1.01	vector_db_benchmarks.VectorDBInsertBenchmarks.time_load_vector_db(2048, 'qdrant')
517±8ms	524±5ms	1.01	vector_db_benchmarks.VectorDBInsertBenchmarks.time_load_vector_db(256, 'chromadb')
34.5±0.7ms	34.4±0.7ms	1.00	benchmarks.time_nb_obj_dir
1.73±0.03s	1.74±0.01s	1.00	benchmarks.time_rebuild_manifest_help

Click here to view all benchmarks.

mtauraso · 2026-01-30T20:08:16Z

CLAUDE.md

+
+Hyrax is model-agnostic and extensible, supporting any PyTorch-based algorithm.
+
+## Development Setup


Many of these sections feel to me like they should be claude skills and incorporated by reference.

A lot of time our robots get bogged down with the amount of dev tooling that is available, and then they don't use the right tool for the job.

mtauraso · 2026-01-30T20:08:44Z

CLAUDE.md

+
+### External Plugin Support
+
+External libraries can provide custom models/datasets/verbs by:


External libraries can't define new verbs (yet)

mtauraso · 2026-01-30T20:09:34Z

CLAUDE.md

+
+### Configuration System
+
+- **TOML-based hierarchical configuration** with strong validation


We should probably document the convention of key=false meaning None for a default, meaning the user must provide a value or the code doesn't run.

mtauraso · 2026-01-30T20:10:00Z

CLAUDE.md

+
+- **TOML-based hierarchical configuration** with strong validation
+- **ConfigManager** merges: `hyrax_default_config.toml` + external library configs + user runtime config
+- **ConfigDict** enforces all keys must have defaults (prevents silent config bugs)


We have relaxed this a bit, might be better omitting it.

mtauraso · 2026-01-30T20:11:40Z

CLAUDE.md

+
+4. LATENT SPACE (Inference)
+   - Infer verb: Model.forward(batch) → latent vectors
+   - InferenceDataSetWriter saves: batch_<N>.npy files + batch_index.npy


We probably shouldn't go to the specificity of data storage format in an overview.

We're working to change that anyway. InferenceDataSetWriter and InferenceDataSet should be reasoned with as if they're a black box at this level that stores results of inference/umap to the results dir in a structured manner that preserves order and ID relationships.

mtauraso · 2026-01-30T20:12:28Z

CLAUDE.md

+   - Optional: SaveToDatabase → ChromaDB for similarity search
+   - Umap verb: reduces latent space to 2D/3D
+
+5. VISUALIZATION/SEARCH


This is the most hacky and specialized verb/stage we have and its fundamentally different from the others in terms of code maturity and testability.

mtauraso · 2026-01-30T20:13:48Z

CLAUDE.md

+- Sample data uses Pooch for reproducible downloads from Zenodo DOIs
+- Pre-commit hook runs fast tests only: `pytest -n auto --cov=./src -m 'not slow'`
+
+## Important Architectural Conventions


This is a little duplicitive of #656, and we may want to incorporate those ideas by reference here.

mtauraso · 2026-01-30T20:14:34Z

CLAUDE.md

+7. **Distributed Training**: PyTorch Ignite's `idist.auto_dataloader()` abstracts single/multi-GPU execution
+8. **External Library Support**: Config system detects `name = "pkg.Class"` and auto-loads `pkg/default_config.toml`
+
+## Code Style


We should probably specify the convention that you should use the linter to correct simple code style issues rather than trying to write all code perfectly.

mtauraso · 2026-01-30T20:14:47Z

CLAUDE.md

+## Code Style
+
+- **Line length**: 110 characters (configured in pyproject.toml)
+- **Python version**: >= 3.9, target 3.9 for compatibility


>= 3.11 now

mtauraso · 2026-01-30T20:15:46Z

CLAUDE.md

+- `src/hyrax/vector_dbs/`: Vector database abstraction (ChromaDB implementation)
+- `tests/hyrax/test_e2e.py`: End-to-end integration tests
+
+## Adding New Components


These also strike me as claude skills

mtauraso · 2026-01-30T20:17:21Z

I don't think I have a clear opinion on whether we should merge or edit here; however, I did put down a lot of comments.

If we want to do one more pass at this, I'd recommend two major focus points

Hierarchical structure: Shorten Claude.md, incorporate significant sub-sections as skills or by reference
Connection to other machine documentation we have, including incorporating parts by reference.

Create HYRAX_GUIDE.md as the canonical shared reference, CLAUDE.md for Claude Code, and rewrite .github/copilot-instructions.md for Copilot. This deduplicates content and fixes inaccuracies identified in PRs #635, #656, and #657: Python version (>=3.11), ConfigDict (Pydantic's, not custom), verbs (internal only), primary interface (notebooks), config philosophy (three-tier "Configuration OR Code"), manifest files (compromise, not design goal), changelogs (none), Pydantic scope (data_request only), and HyraxCifarDataset spelling. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

aritraghsh09 added 2 commits January 27, 2026 10:56

Initial commit of CLAUDE.md

7df2e24

Merge branch 'main' into teaching-the-robots

a29477e

aritraghsh09 requested review from drewoldag, gitosaurus and mtauraso January 27, 2026 19:04

mtauraso reviewed Jan 30, 2026

View reviewed changes

mtauraso mentioned this pull request Jan 30, 2026

Make the robots fix the robot instructions #657

Draft

This was referenced Jan 30, 2026

Restructure robot instructions with hierarchical organization and shared content #658

Merged

Implement Claude Skills for Hyrax development workflows #659

Closed


		Hyrax is model-agnostic and extensible, supporting any PyTorch-based algorithm.

		## Development Setup


		### External Plugin Support

		External libraries can provide custom models/datasets/verbs by:


		### Configuration System

		- TOML-based hierarchical configuration with strong validation

Comments

Conversation

aritraghsh09 commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 27, 2026

Codecov Report

Uh oh!

github-actions bot commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mtauraso Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mtauraso Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mtauraso commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aritraghsh09 commented Jan 27, 2026 •

edited

Loading

mtauraso Jan 30, 2026 •

edited

Loading

mtauraso Jan 30, 2026 •

edited

Loading