Added: Introduce models.dev catalog sync with cached fallbacks

.github/workflows/rust.yml

@@ -52,13 +52,13 @@ jobs:
           cargo +stable binstall --no-confirm cargo-semver-checks --force
           rustup +stable target add ${{ matrix.target }}
 
-          for CRATE in "llm-coding-tools-core" "llm-coding-tools-agents" "llm-coding-tools-serdesai"; do
+          for CRATE in "llm-coding-tools-core" "llm-coding-tools-agents" "llm-coding-tools-serdesai" "llm-coding-tools-models-dev"; do
             SEARCH_RESULT=$(cargo search "^${CRATE}$" --limit 1)
             if echo "$SEARCH_RESULT" | grep -q "^${CRATE} "; then
               echo "Running semver checks for ${CRATE}..."
               # Note: llm-coding-tools-core has mutually exclusive async/blocking features,
               # so we must use --only-explicit-features to avoid enabling all features.
-              # The serdesai crate is async-only and doesn't have the tokio feature.
+              # llm-coding-tools-serdesai is async-only. models-dev supports both tokio and blocking.
               if [ "${CRATE}" = "llm-coding-tools-core" ]; then
                 cargo +stable semver-checks -p "${CRATE}" --target ${{ matrix.target }} --only-explicit-features --features tokio
               else
@@ -79,6 +79,7 @@ jobs:
           cargo doc -p llm-coding-tools-core --features tokio --document-private-items --no-deps --target ${{ matrix.target }}
           cargo doc -p llm-coding-tools-agents --document-private-items --no-deps --target ${{ matrix.target }}
           cargo doc -p llm-coding-tools-serdesai --document-private-items --no-deps --target ${{ matrix.target }}
+          cargo doc -p llm-coding-tools-models-dev --document-private-items --no-deps --target ${{ matrix.target }}
 
       - name: Run linter
         if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/')
@@ -88,6 +89,7 @@ jobs:
           cargo clippy -p llm-coding-tools-core --features tokio --target ${{ matrix.target }} -- -D warnings
           cargo clippy -p llm-coding-tools-agents --target ${{ matrix.target }} -- -D warnings
           cargo clippy -p llm-coding-tools-serdesai --target ${{ matrix.target }} -- -D warnings
+          cargo clippy -p llm-coding-tools-models-dev --target ${{ matrix.target }} -- -D warnings
 
       - name: Run formatter check
         uses: actions-rust-lang/rustfmt@v1
@@ -125,6 +127,7 @@ jobs:
           use-cross: ${{ matrix.use-cross }}
           packages: |
             llm-coding-tools-core
+            llm-coding-tools-models-dev
           no-default-features: true
           features: "blocking"
 
@@ -135,12 +138,14 @@ jobs:
           RUSTDOCFLAGS: "-D warnings"
         run: |
           cargo doc -p llm-coding-tools-core --no-default-features --features blocking --document-private-items --no-deps --target ${{ matrix.target }}
+          cargo doc -p llm-coding-tools-models-dev --no-default-features --features blocking --document-private-items --no-deps --target ${{ matrix.target }}
 
       - name: Run linter (Blocking)
         if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/')
         working-directory: src
         run: |
           cargo clippy -p llm-coding-tools-core --no-default-features --features blocking --target ${{ matrix.target }} -- -D warnings
+          cargo clippy -p llm-coding-tools-models-dev --no-default-features --features blocking --target ${{ matrix.target }} -- -D warnings
 
       - name: Run formatter check
         uses: actions-rust-lang/rustfmt@v1
@@ -165,6 +170,7 @@ jobs:
             src/llm-coding-tools-core
             src/llm-coding-tools-agents
             src/llm-coding-tools-serdesai
+            src/llm-coding-tools-models-dev
           compression-tool: 7z
           artifact-groups-file: .github/artifact-groups.yml
           changelog-enabled: "true"

README.MD

@@ -1,18 +1,30 @@
 # llm-coding-tools
 
 [![Crates.io - llm-coding-tools-core](https://img.shields.io/crates/v/llm-coding-tools-core.svg)](https://crates.io/crates/llm-coding-tools-core)
+[![Crates.io - llm-coding-tools-agents](https://img.shields.io/crates/v/llm-coding-tools-agents.svg)](https://crates.io/crates/llm-coding-tools-agents)
 [![Crates.io - llm-coding-tools-serdesai](https://img.shields.io/crates/v/llm-coding-tools-serdesai.svg)](https://crates.io/crates/llm-coding-tools-serdesai)
+[![Crates.io - llm-coding-tools-models-dev](https://img.shields.io/crates/v/llm-coding-tools-models-dev.svg)](https://crates.io/crates/llm-coding-tools-models-dev)
 [![Docs.rs](https://docs.rs/llm-coding-tools-serdesai/badge.svg)](https://docs.rs/llm-coding-tools-serdesai)
 [![CI](https://github.com/Sewer56/llm-coding-tools/actions/workflows/rust.yml/badge.svg)](https://github.com/Sewer56/llm-coding-tools/actions)
 
-Lightweight, high-performance coding tool implementations for LLM-powered development agents. Plug and play into your favourite frameworks.
+Lightweight, heavily optimized coding tool implementations for LLM-powered
+development agents.
+
+Suitable for server use (<3 MiB), or as building blocks for your own TUI coding agent.
 
 ## About This Workspace
 
-This workspace contains multiple Rust crates for integrating coding tools with LLM agents:
+This workspace contains multiple Rust crates for integrating coding tools with
+LLM agents:
 
-- **[llm-coding-tools-core](./src/llm-coding-tools-core/)**: Framework-agnostic core operations and utilities
-- **[llm-coding-tools-serdesai](./src/llm-coding-tools-serdesai/)**: serdesAI framework-specific Tool implementations
+- **[llm-coding-tools-core](./src/llm-coding-tools-core/)**:
+  Framework-agnostic core operations and utilities
+- **[llm-coding-tools-agents](./src/llm-coding-tools-agents/)**:
+  OpenCode agent markdown loader and typed catalogue
+- **[llm-coding-tools-serdesai](./src/llm-coding-tools-serdesai/)**:
+  serdesAI framework-specific Tool implementations
+- **[llm-coding-tools-models-dev](./src/llm-coding-tools-models-dev/)**:
+  models.dev catalog sync with cached fallback and ETag refresh
 
 ## Features
 
@@ -22,6 +34,9 @@ This workspace contains multiple Rust crates for integrating coding tools with L
 - **Web**: URL fetching with HTML-to-markdown conversion
 - **Path Security**: Choose between unrestricted or sandboxed file access
 - **Context Strings**: Embedded LLM guidance for tool usage
+- **Agent Loading**: Parse OpenCode-compatible agent markdown into typed configs
+- **Model Catalog Sync**: Download and cache the models.dev catalog for
+  provider/model lookups
 
 ## Feature Flags (llm-coding-tools-core)
 
@@ -30,41 +45,24 @@ This workspace contains multiple Rust crates for integrating coding tools with L
 
 ## Quick Start
 
-Add to your `Cargo.toml`:
+Pick the crate that matches your use case:
 
 ```toml
 [dependencies]
-llm-coding-tools-serdesai = "0.1"
+llm-coding-tools-core = "0.2"         # Framework-agnostic tool implementations
+llm-coding-tools-agents = "0.1"       # OpenCode agent markdown loader
+llm-coding-tools-models-dev = "0.1"   # models.dev catalog sync and cache
+llm-coding-tools-serdesai = "0.2"     # serdesAI integration
 ```
 
-```rust,no_run
-use llm_coding_tools_serdesai::{AgentBuilder, BashTool, TodoTools};
-use llm_coding_tools_serdesai::absolute::{ReadTool, WriteTool, EditTool, GlobTool, GrepTool};
-
-let mut builder = AgentBuilder::new();
-let todos = TodoTools::new();
-
-builder
-    .track(ReadTool::<true>::new())
-    .track(WriteTool::new())
-    .track(EditTool::<true>::new())
-    .track(GlobTool::new())
-    .track(GrepTool::<true>::new())
-    .track(BashTool::new())
-    .track(&todos.read)
-    .track(&todos.write);
-
-let mut agent = builder.build();
-
-// Use the agent
-// let response = agent.invoke("List all files").await?;
-```
+For a runnable agent setup, start with `llm-coding-tools-serdesai` and the
+examples below.
 
 ## Examples
 
 ```bash
 # serdesAI framework - Basic agent setup
-cargo run --example serdesai-agents -p llm-coding-tools-serdesai
+cargo run --example serdesai-basic -p llm-coding-tools-serdesai
 
 # serdesAI framework - Sandboxed file access
 cargo run --example serdesai-sandboxed -p llm-coding-tools-serdesai
@@ -73,18 +71,26 @@ cargo run --example serdesai-sandboxed -p llm-coding-tools-serdesai
 ## Documentation
 
 - [llm-coding-tools-core README](./src/llm-coding-tools-core/README.md)
+- [llm-coding-tools-agents README](./src/llm-coding-tools-agents/README.md)
 - [llm-coding-tools-serdesai README](./src/llm-coding-tools-serdesai/README.md)
+- [llm-coding-tools-models-dev README](./src/llm-coding-tools-models-dev/README.md)
 - [Developer Guidelines](./src/AGENTS.md)
 
 ## Contributing
 
-Contributions are welcome! Please ensure all tests pass and the code follows our guidelines.
+Contributions are welcome! Please ensure all tests pass and the code follows
+our guidelines.
 
 ## Deprecation Notice
 
-**Rig framework support (`llm-coding-tools-rig`) has been removed** (commit 17158db) due to library bugs that prevented examples from running reliably.
+**Rig framework support (`llm-coding-tools-rig`) has been removed**
+(commit 17158db) due to library bugs that prevented examples from running
+reliably.
 
-You're welcome to submit a PR re-adding rig support if you're willing to maintain it. Since I don't use rig personally, I'm not able to actively maintain that integration. Alternatively, you can create your own crate building on `llm-coding-tools-core` directly.
+You're welcome to submit a PR re-adding rig support if you're willing to
+maintain it. Since I don't use rig personally, I'm not able to actively
+maintain that integration. Alternatively, you can create your own crate
+building on `llm-coding-tools-core` directly.
 
 ## License
 

src/.cargo/verify.ps1

@@ -2,8 +2,8 @@
 # All steps must pass without warnings
 # Keep in sync with verify.sh
 #
-# Note: llm-coding-tools-serdesai is async-only (implements async Tool traits).
-# The blocking feature only applies to llm-coding-tools-core.
+# Note: llm-coding-tools-serdesai is async-only.
+# Blocking mode is validated for core and models-dev.
 
 $ErrorActionPreference = "Stop"
 
@@ -35,25 +35,29 @@ try {
 Invoke-LoggedCommand "cargo" @("build", "-p", "llm-coding-tools-core", "--quiet")
 Invoke-LoggedCommand "cargo" @("build", "-p", "llm-coding-tools-agents", "--quiet")
 Invoke-LoggedCommand "cargo" @("build", "-p", "llm-coding-tools-serdesai", "--quiet")
+Invoke-LoggedCommand "cargo" @("build", "-p", "llm-coding-tools-models-dev", "--quiet")
 
 Write-Host "Testing..."
 Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-core", "--quiet")
 Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-agents", "--quiet")
 Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-serdesai", "--quiet")
+Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-models-dev", "--quiet")
 
 Write-Host "Clippy..."
 Invoke-LoggedCommand "cargo" @("clippy", "-p", "llm-coding-tools-core", "--quiet", "--", "-D", "warnings")
 Invoke-LoggedCommand "cargo" @("clippy", "-p", "llm-coding-tools-agents", "--quiet", "--", "-D", "warnings")
 Invoke-LoggedCommand "cargo" @("clippy", "-p", "llm-coding-tools-serdesai", "--quiet", "--", "-D", "warnings")
+Invoke-LoggedCommand "cargo" @("clippy", "-p", "llm-coding-tools-models-dev", "--quiet", "--", "-D", "warnings")
 
 Write-Host "Testing blocking feature..."
 Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-core", "--no-default-features", "--features", "blocking", "--quiet")
+Invoke-LoggedCommand "cargo" @("test", "-p", "llm-coding-tools-models-dev", "--no-default-features", "--features", "blocking", "--quiet")
 
 Write-Host "Docs..."
 $originalRustdocFlags = $env:RUSTDOCFLAGS
 $env:RUSTDOCFLAGS = "-D warnings"
 try {
-    Invoke-LoggedCommand "cargo" @("doc", "--workspace", "--no-deps", "--quiet")
+    Invoke-LoggedCommand "cargo" @("doc", "--workspace", "--document-private-items", "--no-deps", "--quiet")
 } finally {
     $env:RUSTDOCFLAGS = $originalRustdocFlags
 }
@@ -65,6 +69,7 @@ Write-Host "Publish dry-run..."
 Invoke-LoggedCommand "cargo" @("publish", "--dry-run", "--allow-dirty", "-p", "llm-coding-tools-core", "--quiet")
 Invoke-LoggedCommand "cargo" @("publish", "--dry-run", "--allow-dirty", "-p", "llm-coding-tools-agents", "--quiet")
 Invoke-LoggedCommand "cargo" @("publish", "--dry-run", "--allow-dirty", "-p", "llm-coding-tools-serdesai", "--quiet")
+Invoke-LoggedCommand "cargo" @("publish", "--dry-run", "--allow-dirty", "-p", "llm-coding-tools-models-dev", "--quiet")
 
 Write-Host "All checks passed!"
 }

src/.cargo/verify.sh

@@ -3,8 +3,8 @@
 # All steps must pass without warnings
 # Keep in sync with verify.ps1
 #
-# Note: llm-coding-tools-serdesai is async-only (implements async Tool traits).
-# The blocking feature only applies to llm-coding-tools-core.
+# Note: llm-coding-tools-serdesai is async-only.
+# Blocking mode is validated for core and models-dev.
 
 set -e
 
@@ -24,22 +24,26 @@ echo "Building..."
 run_cmd cargo build -p llm-coding-tools-core --quiet
 run_cmd cargo build -p llm-coding-tools-agents --quiet
 run_cmd cargo build -p llm-coding-tools-serdesai --quiet
+run_cmd cargo build -p llm-coding-tools-models-dev --quiet
 
 echo "Testing..."
 run_cmd cargo test -p llm-coding-tools-core --quiet
 run_cmd cargo test -p llm-coding-tools-agents --quiet
 run_cmd cargo test -p llm-coding-tools-serdesai --quiet
+run_cmd cargo test -p llm-coding-tools-models-dev --quiet
 
 echo "Clippy..."
 run_cmd cargo clippy -p llm-coding-tools-core --quiet -- -D warnings
 run_cmd cargo clippy -p llm-coding-tools-agents --quiet -- -D warnings
 run_cmd cargo clippy -p llm-coding-tools-serdesai --quiet -- -D warnings
+run_cmd cargo clippy -p llm-coding-tools-models-dev --quiet -- -D warnings
 
 echo "Testing blocking feature..."
 run_cmd cargo test -p llm-coding-tools-core --no-default-features --features blocking --quiet
+run_cmd cargo test -p llm-coding-tools-models-dev --no-default-features --features blocking --quiet
 
 echo "Docs..."
-run_cmd env RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --quiet
+run_cmd env RUSTDOCFLAGS="-D warnings" cargo doc --workspace --document-private-items --no-deps --quiet
 
 echo "Formatting..."
 run_cmd cargo fmt --all --check --quiet
@@ -48,5 +52,6 @@ echo "Publish dry-run..."
 run_cmd cargo publish --dry-run --allow-dirty -p llm-coding-tools-core --quiet
 run_cmd cargo publish --dry-run --allow-dirty -p llm-coding-tools-agents --quiet
 run_cmd cargo publish --dry-run --allow-dirty -p llm-coding-tools-serdesai --quiet
+run_cmd cargo publish --dry-run --allow-dirty -p llm-coding-tools-models-dev --quiet
 
 echo "All checks passed!"