Skip to content

added CLAUDE.md file #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
puja-trivedi merged 1 commit into from
Jan 23, 2026
Merged

added CLAUDE.md file #86

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

bkbit (Brain Knowledge Base Interaction Toolkit) is a Python library for working with BICAN (Brain Initiative Cell Atlas Network) Knowledgebase Data Models. It contains Pydantic versions of the BICAN models along with tools for data translation, model conversion, and model editing.

## Development Setup

```bash
# Install in editable mode with all dependencies
pip install -e .[all]

# Install newer schemasheets version (temporary fix)
pip install git+https://github.com/linkml/schemasheets
```

## Commands

### Testing
```bash
# Run all tests
pytest

# Run a specific test file
pytest bkbit/tests/test_specimen_portal_translator.py

# Run a specific test
pytest bkbit/tests/test_specimen_portal_translator.py::test_library_pool
```

### Linting and Formatting
```bash
# Format with black
black .

# Run pre-commit hooks
pre-commit run --all-files
```

### CLI Usage
The package provides a CLI tool `bkbit` with multiple subcommands:
- `bkbit specimen2jsonld` - Generate BICAN objects from Specimen Portal data
- `bkbit gff2jsonld` - Generate genome annotation objects from GFF3 files
- `bkbit taxonomy2jsonld` - Generate taxonomy objects from HMBA annotations
- `bkbit schema2model` - Convert spreadsheets to LinkML YAML models
- `bkbit yaml2cvs` - Convert YAML to CSV
Copy link

@gemini-code-assist gemini-code-assist bot Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There's a typo in the subcommand name. Based on bkbit/cli.py and bkbit/model_converters/yaml2sheet_converter.py, the command should be yaml2csv to accurately reflect its function of converting YAML to CSV.

Suggested change
- `bkbit yaml2cvs` - Convert YAML to CSV
- `bkbit yaml2csv` - Convert YAML to CSV

Copy link
Collaborator Author

@puja-trivedi puja-trivedi Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the suggestion is valid and needs to be fixed; however, it would require changing the name in multiple places. Will require a separate PR

- `bkbit linkml-trimmer` - Trim LinkML models
- `bkbit download-ncbi-taxonomy` - Download NCBI taxonomy data

## Architecture

### Core Modules

**`bkbit/models/`** - Pydantic model definitions generated from LinkML schemas:
- `library_generation.py` - Library generation workflow models
- `genome_annotation.py` - Genome annotation models
- `anatomical_structure.py` - Anatomical structure models

**`bkbit/data_translators/`** - Convert external data sources to BICAN model instances:
- `library_generation_translator.py` - Specimen Portal to BICAN objects (specimen2jsonld)
- `genome_annotation_translator.py` - GFF3 files to genome annotation objects (gff2jsonld)
- `HMBA_annotation_translator.py` - HMBA taxonomy annotations (taxonomy2jsonld)
- `specimen_metadata_translator.py` - Specimen metadata handling

**`bkbit/model_converters/`** - Tools for converting between formats:
- `sheets_converter.py` - Google Sheets/TSV to LinkML YAML (schema2model)
- `yaml2sheet_converter.py` - YAML to CSV conversion

**`bkbit/model_editors/`** - Tools for modifying LinkML models:
- `linkml_trimmer.py` - Trims LinkML models to include only specified classes/slots/enums
- `add_dunderMethods_genomeAnnotation.py` - Adds __eq__, __ne__, __hash__ to GeneAnnotation
Copy link

@gemini-code-assist gemini-code-assist bot Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The filename add_dunderMethods_genomeAnnotation.py appears to have a typo in dunderMethods. It should be dunder_methods for better readability and to follow Python's naming conventions for dunder (double underscore) methods.

Suggested change
- `add_dunderMethods_genomeAnnotation.py` - Adds __eq__, __ne__, __hash__ to GeneAnnotation
- `add_dunder_methods_genomeAnnotation.py` - Adds __eq__, __ne__, __hash__ to GeneAnnotation

Copy link
Collaborator Author

@puja-trivedi puja-trivedi Jan 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the suggestion is valid (but low priority); however, it would require changing the name in multiple places. Would require a separate PR


**`bkbit/utils/`** - Shared utilities:
- `get_ncbi_taxonomy.py` - NCBI taxonomy download
- `nimp_api_endpoints.py` - Specimen Portal API endpoints
- `setup_logger.py` - Logging configuration

### External Dependencies
- **LinkML** - Schema definition language for the models
- **Schemasheets** - Spreadsheet to LinkML conversion
- **Click** - CLI framework

### Environment Variables
- `jwt_token` - Specimen Portal Personal API Token (required for specimen2jsonld)
Loading