---
id: nsip-readme
type: semantic
created: 2026-02-07T14:26:06-05:00
namespace: nsip
modified: '2026-08-11T17:59:14.628Z'
title: "`nsip`"
provenance:
'@type': Provenance
agent: claude-code/claude-sonnet-5
wasGeneratedBy:
'@id': urn:mif:activity:claude-code-session:f2ea9348-10db-44af-9ccb-a37844b8c1f2
'@type': prov:Activity
trustLevel: user_stated
agentVersion: 2.1.227
---
# `nsip`
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/social-preview-dark.svg">
<source media="(prefers-color-scheme: light)" srcset=".github/social-preview.svg">
<img alt="nsip - Sheep Genetic Evaluation Tools" src=".github/social-preview.svg" width="100%">
</picture>
[](https://github.com/zircote/nsip/actions/workflows/ci.yml)
[](https://crates.io/crates/nsip)
[](https://docs.rs/nsip)
[](https://www.rust-lang.org/)
[](https://github.com/zircote/nsip/blob/main/LICENSE)
[](https://github.com/rust-lang/rust-clippy)
[](https://github.com/EmbarkStudios/cargo-deny)
[](https://github.com/gitleaks/gitleaks)
[](https://docs.github.com/en/code-security/dependabot)
Sheep genetic evaluation CLI & MCP server -- search animals, compare EBVs, plan matings, rank flocks via the NSIP database.
<p align="center">
<img src=".github/readme-infographic.svg" alt="NSIP Architecture Overview" width="800">
</p>
> **Try it out:** Clone [zircote/nsip-example](https://github.com/zircote/nsip-example) for a ready-to-use farm repository with MCP server configuration, sample workflows, and AI assistant instructions pre-configured.
## Features
- **Type-safe API client** with comprehensive error handling
- **Search functionality** for animals by breed group, status, and other criteria
- **Detailed animal information** including lineage and progeny
- **MCP (Model Context Protocol) integration** for AI assistant compatibility
- **CLI tool** with multiple subcommands for easy interaction
- **Async/await support** with tokio runtime
- **Full documentation** with examples in all public APIs
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
nsip = "0.6"
```
Or use cargo add:
```bash
cargo add nsip
```
## Quick Start
```rust,no_run
use nsip::{NsipClient, SearchCriteria};
#[tokio::main]
async fn main() -> Result<(), nsip::Error> {
// Create a new client
let client = NsipClient::new();
// List available breed groups
let breed_groups = client.breed_groups().await?;
println!("Available breed groups: {}", breed_groups.len());
// Search for animals
let criteria = SearchCriteria::new()
.with_status("CURRENT");
let results = client
.search_animals(0, 15, Some(640), None, None, Some(&criteria))
.await?;
println!("Found {} animals", results.total_count);
// Get details for a specific animal
let animal = client.animal_details("LPN_ID_HERE").await?;
println!("Animal: {}", animal.lpn_id);
Ok(())
}
```
## CLI Usage
The `nsip` CLI provides several commands for interacting with the NSIP Search API:
```bash
# Get database last-updated date
nsip date-updated
# List breed groups
nsip breed-groups
# List animal statuses
nsip statuses
# Get trait ranges for a breed
nsip trait-ranges 640
# Search for animals
nsip search --breed-id 640 --status CURRENT --page 0 --page-size 15
# Get animal details
nsip details <lpn-id>
# Get animal lineage
nsip lineage <lpn-id>
# Get animal progeny
nsip progeny <lpn-id>
# Get full profile (details + lineage + progeny)
nsip profile <lpn-id>
# Compare two or more animals side-by-side
nsip compare <lpn-id-1> <lpn-id-2>
# Generate shell completions
nsip completions bash
# Generate man pages
nsip man-pages --out-dir ./man/
# Start MCP server mode
nsip mcp
```
## API Overview
### Client Methods
| `date_last_updated()` | Get database last-updated date |
| `breed_groups()` | List available breed groups |
| `statuses()` | List available animal statuses |
| `trait_ranges(breed_id)` | Get trait ranges for a breed |
| `search_animals(page, page_size, breed_id, sorted_trait, reverse, criteria)` | Search for animals |
| `animal_details(search_string)` | Get animal details |
| `lineage(lpn_id)` | Get animal lineage |
| `progeny(lpn_id, page, page_size)` | Get animal progeny |
| `search_by_lpn(lpn_id)` | Get full profile (concurrent) |
### Data Types
| `NsipClient` | Main API client |
| `SearchCriteria` | Search parameters with builder pattern |
| `AnimalDetails` | Detailed animal record with traits and contact info |
| `AnimalProfile` | Combined details + lineage + progeny |
| `Breed` | A single breed within a breed group |
| `BreedGroup` | Breed group with nested breeds |
| `ContactInfo` | Owner / flock contact information |
| `DateLastUpdated` | Response from the date-last-updated endpoint |
| `Lineage` | Animal lineage/ancestry tree |
| `LineageAnimal` | A single node in the pedigree tree |
| `Progeny` | Paginated animal offspring |
| `ProgenyAnimal` | A single offspring record |
| `SearchResults` | Paginated search results |
| `Trait` | A single EBV trait with value and accuracy |
| `TraitRange` | Min/max range for a trait within a breed |
| `TraitRangeFilter` | Min/max bounds for a trait filter |
| `Error` | Error type for operations |
| `Result<T>` | Type alias for `Result<T, Error>` |
## Documentation
Full documentation lives under [`docs/`](docs/README.md), organized using the [Diataxis framework](https://diataxis.fr/):
- [Getting Started Tutorial](docs/tutorials/GETTING-STARTED.md) - 15-minute hands-on introduction to the CLI and library
- [MCP Server Reference](docs/MCP.md) - full API reference for the built-in MCP server
- [CLI Reference](docs/reference/CLI.md) - every subcommand, flag, and option
- [Library API Reference](docs/reference/LIBRARY-API.md) - types and methods for the `nsip` crate
See [`docs/README.md`](docs/README.md) for the complete documentation index.
## MCP Integration
The library includes MCP (Model Context Protocol) support for integration with AI assistants:
```rust,ignore
use nsip::mcp::{serve_stdio, tool_sets::EnabledToolSets};
// Start the MCP server on stdio (all 13 tools enabled)
serve_stdio(EnabledToolSets::all()).await?;
```
The MCP protocol exposes the following 13 tools when running `nsip mcp`:
- `search` - Search for animals with filters for breed, gender, status, date range, and flock
- `details` - Get detailed EBV data, breed, contact info, and status for an animal
- `lineage` - Get pedigree / ancestry tree including parents and grandparents
- `progeny` - Get paginated list of offspring for an animal
- `profile` - Get complete profile (details + pedigree + offspring) in one call
- `breed_groups` - List all breed groups and individual breeds
- `trait_ranges` - Get min/max EBV trait ranges for a specific breed
- `compare` - Compare 2-5 animals side-by-side on their EBV traits
- `rank` - Rank animals within a breed by weighted EBV traits
- `inbreeding_check` - Calculate Wright's coefficient of inbreeding for a sire-dam pairing
- `mating_recommendations` - Find optimal mates ranked by trait complementarity and COI
- `flock_summary` - Summarize a flock's animals: count, gender breakdown, and average EBVs
- `database_status` - Get last-updated date and available animal statuses
## Development
### Prerequisites
- Rust 1.92+ (2024 edition)
- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) for supply chain security
### Setup
```bash
# Clone the repository
git clone https://github.com/zircote/nsip.git
cd nsip
# Build
cargo build
# Run tests
cargo test
# Run linting
cargo clippy --all-targets --all-features
# Format code
cargo fmt
# Check supply chain security
cargo deny check
# Generate documentation
cargo doc --open
```
### Project Structure
```text
crates/
├── lib.rs # Library entry point
├── main.rs # Binary entry point
├── client.rs # HTTP client for the NSIP Search API
├── models.rs # Data models (SearchCriteria, AnimalDetails, etc.)
├── format.rs # Human-readable ASCII table formatting
└── mcp/ # MCP server (13 tools, prompts, resources)
tests/
├── integration_test.rs
└── cli_test.rs # CLI integration tests
Cargo.toml # Project manifest
clippy.toml # Clippy configuration
rustfmt.toml # Formatter configuration
deny.toml # cargo-deny configuration
CLAUDE.md # AI assistant instructions
AGENTS.md # AI coding agent instructions
.editorconfig # Cross-editor defaults
.devcontainer/ # Codespaces / dev container config
.vscode/ # VS Code settings and extensions
```
### Code Quality
This project maintains high code quality standards:
- **Linting**: clippy with pedantic and nursery lints
- **Formatting**: rustfmt with custom configuration
- **Testing**: Unit tests, integration tests, and property-based tests
- **Documentation**: All public APIs documented with examples
- **Supply Chain**: cargo-deny for dependency auditing
- **CI/CD**: GitHub Actions for automated testing
### Running Checks
> **Note:** [`just check`](https://github.com/casey/just) is the canonical local
> equivalent of the CI pipeline (fmt + clippy + test + doc + deny + coverage).
> Run `just` to list all available recipes. The raw `cargo` commands below are
> the underlying equivalents.
```bash
# Run all checks
cargo fmt -- --check && \
cargo clippy --all-targets --all-features -- -D warnings && \
cargo test && \
cargo doc --no-deps && \
cargo deny check
# Run with MIRI for undefined behavior detection
cargo +nightly miri test
```
## CI/CD and Deployment
This template includes production-ready workflows:
### Continuous Integration
- **CI** (`.github/workflows/ci.yml`) - Format, lint, test, docs, supply chain security, MSRV check, coverage
- **Security Audit** (`.github/workflows/security-audit.yml`) - Daily cargo-audit scans
- **Secrets Scan** (`.github/workflows/secrets-scan.yml`) - Gitleaks secret scanning (manual; enable push/PR triggers to automate)
- **Container Scan** (`.github/workflows/container-scan.yml`) - Trivy image vulnerability scanning
### Release and Deployment
- **Release** (`.github/workflows/release.yml`) - Automated GitHub releases with multi-platform binaries
- Builds for: Linux (`x86_64`, ARM64), macOS (`x86_64`, ARM64), Windows (`x86_64`)
- Automatic changelog generation
- Binary artifacts uploaded to releases
- **Changelog** (`.github/workflows/changelog.yml`) - Automated CHANGELOG.md generation
- Uses git-cliff with conventional commits
- Follows Keep a Changelog format
- Triggered on version tags
- **Docker** (`.github/workflows/docker.yml`) - Multi-platform container builds
- Platforms: linux/amd64, linux/arm64
- Distroless base image for security
- Published to GitHub Container Registry (ghcr.io)
- Tagged with version and 'latest'
- **Publish** (`.github/workflows/publish.yml`) - Automated crates.io publishing
- Full pre-publish validation
- Triggered on version tags
- Trusted Publishing (OIDC) — no registry token; the published crate is byte-verified and attested
### Creating a Release
`develop` is the active development branch and `main` is the stable/release branch. **Never tag from `develop`** — promote the release through `main` first via the `Release PR` workflow. See [`docs/runbooks/RELEASING.md`](docs/runbooks/RELEASING.md) for the full step-by-step procedure; summary:
1. Bump the version in `Cargo.toml` on `develop`.
2. Run `gh workflow run "Release PR" -f version=X.Y.Z`, get it reviewed, and merge it into `main`.
3. Tag the `main` merge commit and push the tag:
```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
```
4. The tag triggers workflows that automatically:
- Generate the changelog
- Build and attest binaries for all platforms
- Create the GitHub release with artifacts
- Build and push Docker images
- Publish to crates.io
- Update the Homebrew tap
- Back-merge `main` into `develop`
### AI Coding Agent
- **Copilot Setup** (`.github/workflows/copilot-setup-steps.yml`) - Environment for GitHub Copilot coding agent
- **Agent Instructions**: `AGENTS.md`, `.github/copilot-instructions.md`, `CLAUDE.md`
- **Path-Specific Instructions**: `.github/instructions/` for Rust code and test patterns
- **Reusable Prompts**: `.github/prompts/` for common development tasks
### Docker Usage
Pull and run the container:
```bash
# Pull latest
docker pull ghcr.io/zircote/nsip:latest
# Run specific version
docker pull ghcr.io/zircote/nsip:v0.6.0
docker run --rm ghcr.io/zircote/nsip:v0.6.0 --version
```
## MSRV Policy
The Minimum Supported Rust Version (MSRV) is **1.92**. Increasing the MSRV is considered a minor breaking change.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR checklist, and coding standards.
Please also review:
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community guidelines
- [SECURITY.md](SECURITY.md) - Vulnerability reporting
- [GOVERNANCE.md](GOVERNANCE.md) - Decision-making process
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/zircote/nsip/blob/main/LICENSE) file for details.
## Acknowledgments
- [The Rust Programming Language](https://www.rust-lang.org/)
- [Cargo](https://doc.rust-lang.org/cargo/)
- [clippy](https://github.com/rust-lang/rust-clippy)