Skip to content

Commit 5fc7551

Browse files
nicolasnoblenicolasnoble
committed
chore: Updating agents instructions + Adding Claude Code ones.
Signed-off-by: Nicolas Pixel Noble <pixel@nobis-crew.org>
1 parent b6830a9 commit 5fc7551

File tree

3 files changed

+153
-0
lines changed

3 files changed

+153
-0
lines changed

‎.cursor/rules/rust.mdc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,33 @@ The project is split in 3 separate crates:
3232
2. `common`: Provides shared utilities and data structures for the model. Any constant definitions should be placed here. As much as possible, any shared logic should also be placed here.
3333
3. `server`: Implements the server-side logic and API endpoints for ModelExpress in a stand alone server.
3434

35+
## Adding CLI Arguments
36+
37+
Client CLI arguments are defined in a shared struct to avoid duplication:
38+
39+
1. **Add to `ClientArgs`** in `modelexpress_common/src/client_config.rs`:
40+
- This is the single source of truth for shared arguments
41+
- Use `#[arg(long, env = "MODEL_EXPRESS_...")]` for environment variable support
42+
- Do NOT use `-v` short flag (reserved for CLI's verbose)
43+
44+
2. **Update `ClientConfig::load()`** in the same file:
45+
- Add override logic in the "APPLY CLI ARGUMENT OVERRIDES" section
46+
47+
3. **Do NOT duplicate in `Cli`** (`modelexpress_client/src/bin/modules/args.rs`):
48+
- `Cli` embeds `ClientArgs` via `#[command(flatten)]`
49+
- Only add CLI-specific arguments there (e.g., `--format`, `--verbose`)
50+
51+
4. **Add tests** in the `tests` module of `client_config.rs`
52+
3553
# Code quality
3654

3755
- Do **NOT** use emojis. These are unprofessional.
3856
- Do not create markdown files to document code changes or decisions.
3957
- Do not over-comment code. Removing code is fine without adding new comments to explain why.
58+
59+
# AI Agent Instructions
60+
61+
When introducing new patterns, conventions, or architectural decisions that affect how code should be written, update ALL AI agent instruction files:
62+
- `CLAUDE.md` (Claude Code)
63+
- `.github/copilot-instructions.md` (GitHub Copilot)
64+
- `.cursor/rules/rust.mdc` (Cursor)

‎.github/copilot-instructions.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,33 @@ The project is split in 3 separate crates:
3030
2. `common`: Provides shared utilities and data structures for the model. Any constant definitions should be placed here. As much as possible, any shared logic should also be placed here.
3131
3. `server`: Implements the server-side logic and API endpoints for ModelExpress in a stand alone server.
3232

33+
## Adding CLI Arguments
34+
35+
Client CLI arguments are defined in a shared struct to avoid duplication:
36+
37+
1. **Add to `ClientArgs`** in `modelexpress_common/src/client_config.rs`:
38+
- This is the single source of truth for shared arguments
39+
- Use `#[arg(long, env = "MODEL_EXPRESS_...")]` for environment variable support
40+
- Do NOT use `-v` short flag (reserved for CLI's verbose)
41+
42+
2. **Update `ClientConfig::load()`** in the same file:
43+
- Add override logic in the "APPLY CLI ARGUMENT OVERRIDES" section
44+
45+
3. **Do NOT duplicate in `Cli`** (`modelexpress_client/src/bin/modules/args.rs`):
46+
- `Cli` embeds `ClientArgs` via `#[command(flatten)]`
47+
- Only add CLI-specific arguments there (e.g., `--format`, `--verbose`)
48+
49+
4. **Add tests** in the `tests` module of `client_config.rs`
50+
3351
# Code quality
3452

3553
- Do **NOT** use emojis. These are unprofessional.
3654
- Do not create markdown files to document code changes or decisions.
3755
- Do not over-comment code. Removing code is fine without adding new comments to explain why.
56+
57+
# AI Agent Instructions
58+
59+
When introducing new patterns, conventions, or architectural decisions that affect how code should be written, update ALL AI agent instruction files:
60+
- `CLAUDE.md` (Claude Code)
61+
- `.github/copilot-instructions.md` (GitHub Copilot)
62+
- `.cursor/rules/rust.mdc` (Cursor)

‎CLAUDE.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build and Development Commands
6+
7+
```bash
8+
# Build the project
9+
cargo build
10+
11+
# Build in release mode
12+
cargo build --release
13+
14+
# Run the server
15+
cargo run --bin modelexpress-server
16+
17+
# Run tests
18+
cargo test
19+
20+
# Run integration tests (starts server, runs test client)
21+
./run_integration_tests.sh
22+
23+
# Run a specific test client
24+
cargo run --bin test_client -- --test-model "google-t5/t5-small"
25+
26+
# Run clippy (required before submitting code)
27+
cargo clippy
28+
29+
# Generate sample configuration file
30+
cargo run --bin config_gen -- --output model-express.yaml
31+
```
32+
33+
## Architecture
34+
35+
ModelExpress is a Rust-based model cache management service that accelerates inference by caching HuggingFace models. It can be deployed standalone or as a sidecar alongside inference solutions like NVIDIA Dynamo.
36+
37+
### Workspace Structure
38+
39+
The project is a Rust workspace with three crates:
40+
41+
- **`modelexpress_server`** (`modelexpress-server`): gRPC server providing model services
42+
- `services.rs`: Implements `HealthService`, `ApiService`, and `ModelService` gRPC services
43+
- `database.rs`: SQLite-based model status persistence via `ModelDatabase`
44+
- `cache.rs`: Cache eviction and management
45+
- Uses global `MODEL_TRACKER` (`LazyLock<ModelDownloadTracker>`) for tracking download state
46+
47+
- **`modelexpress_client`** (`modelexpress-client`): Client library and CLI tool
48+
- `lib.rs`: Main `Client` struct with gRPC clients for health, API, and model services
49+
- `bin/cli.rs`: HuggingFace CLI replacement for model downloads
50+
- Supports automatic fallback to direct download when server unavailable
51+
52+
- **`modelexpress_common`** (`modelexpress-common`): Shared code and protobuf definitions
53+
- `grpc/` module contains generated proto code (health, api, model)
54+
- `providers/huggingface.rs`: HuggingFace download implementation
55+
- `download.rs`: Provider-agnostic download orchestration
56+
- `cache.rs`, `config.rs`, `client_config.rs`: Configuration types
57+
58+
### gRPC Services
59+
60+
Protocol definitions are in `modelexpress_common/proto/`:
61+
- `health.proto`: Health check endpoint
62+
- `api.proto`: Generic request/response API
63+
- `model.proto`: Model download with streaming status updates
64+
65+
### Key Patterns
66+
67+
- Download status tracked in SQLite database with compare-and-swap for concurrent request handling
68+
- Streaming gRPC responses for download progress updates via `ModelStatusUpdate`
69+
- `CacheConfig::discover()` finds cache configuration from environment or config files
70+
- Configuration layering: CLI args > environment variables > config files > defaults
71+
72+
### Adding CLI Arguments
73+
74+
Client CLI arguments and environment variables are defined in a shared struct to avoid duplication:
75+
76+
1. **`ClientArgs`** in `modelexpress_common/src/client_config.rs`:
77+
- Single source of truth for shared client arguments (endpoint, timeout, cache settings, etc.)
78+
- Add new arguments here with `#[arg(long, env = "MODEL_EXPRESS_...")]`
79+
- Avoid `-v` short flag (reserved for CLI's verbose)
80+
81+
2. **`ClientConfig::load()`** in the same file:
82+
- Apply the new argument to the config struct in the "APPLY CLI ARGUMENT OVERRIDES" section
83+
84+
3. **`Cli`** in `modelexpress_client/src/bin/modules/args.rs`:
85+
- Embeds `ClientArgs` via `#[command(flatten)]`
86+
- Only add CLI-specific arguments here (e.g., `--format`, `--verbose`)
87+
88+
4. **Tests**: Add tests in `client_config.rs` for argument parsing and config loading
89+
90+
## Code Standards
91+
92+
- **No `unwrap()`**: Strictly forbidden except in benchmarks. Use `match`, `?`, or `expect()` (tests only)
93+
- **All dependencies in root `Cargo.toml`**: Sub-crates use workspace dependencies exclusively
94+
- **Clippy enforced**: `cargo clippy` must pass with no warnings (multiple lints set to deny)
95+
- **No emojis in code**
96+
- **No markdown documentation files for code changes**
97+
98+
## AI Agent Instructions
99+
100+
When introducing new patterns, conventions, or architectural decisions that affect how code should be written, update ALL AI agent instruction files:
101+
- `CLAUDE.md` (Claude Code)
102+
- `.github/copilot-instructions.md` (GitHub Copilot)
103+
- `.cursor/rules/rust.mdc` (Cursor)

0 commit comments

Comments
 (0)