BUG-HUNT: [spec-alignment] Missing Hugging Face provider #3018

Open
opened 2026-04-05 03:54:20 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/spec-alignment-huggingface-provider
  • Commit Message: fix(providers): add HUGGINGFACE to ProviderType enum and implement HuggingFaceChatProvider
  • Milestone: v3.3.0
  • Parent Epic: #362

Bug Report: [spec-alignment] — Missing Hugging Face provider

Severity Assessment

  • Impact: The Hugging Face provider is entirely absent from the providers module. Any user or configuration that references provider.huggingface.token or the HF_TOKEN environment variable will receive no provider resolution, causing silent failures or runtime errors when attempting to use Hugging Face-backed models.
  • Likelihood: High. The specification explicitly names Hugging Face as a supported provider with a dedicated configuration key and environment variable. Any user following the specification will encounter this gap immediately.
  • Priority: Medium

Location

  • File: src/cleveragents/providers/registry.py
  • Function/Class: ProviderType

Description

The specification defines Hugging Face as a first-class LLM provider, documented with the configuration key provider.huggingface.token and the environment variable HF_TOKEN. However, the providers module contains no trace of this provider. Specifically:

  • The ProviderType enum is missing a HUGGINGFACE value.
  • DEFAULT_CAPABILITIES has no entry for ProviderType.HUGGINGFACE.
  • DEFAULT_MODELS has no entry for ProviderType.HUGGINGFACE.
  • PROVIDER_KEY_ATTRS has no entry mapping ProviderType.HUGGINGFACE to its configuration key (provider.huggingface.token) or environment variable (HF_TOKEN).
  • No HuggingFaceChatProvider class exists anywhere in the providers package.

Evidence

The specification mentions the provider.huggingface.token configuration key and the HF_TOKEN environment variable as the canonical way to configure the Hugging Face provider. A search of src/cleveragents/providers/registry.py reveals zero references to huggingface, HUGGINGFACE, or HF_TOKEN.

Expected Behavior

The Hugging Face provider should be fully implemented in the providers module, consistent with all other supported providers:

  1. ProviderType.HUGGINGFACE enum value present in registry.py.
  2. A corresponding entry in DEFAULT_CAPABILITIES describing the provider's supported capabilities.
  3. A corresponding entry in DEFAULT_MODELS listing the default model(s) for the provider.
  4. A corresponding entry in PROVIDER_KEY_ATTRS mapping ProviderType.HUGGINGFACE to provider.huggingface.token / HF_TOKEN.
  5. A HuggingFaceChatProvider class implementing the provider interface, reading credentials from HF_TOKEN.

Actual Behavior

The ProviderType enum, DEFAULT_CAPABILITIES, DEFAULT_MODELS, and PROVIDER_KEY_ATTRS all lack any Hugging Face entry. The provider cannot be selected, configured, or used at runtime.

Suggested Fix

  1. Add HUGGINGFACE = "huggingface" to the ProviderType enum in src/cleveragents/providers/registry.py.
  2. Add a DEFAULT_CAPABILITIES[ProviderType.HUGGINGFACE] entry reflecting the provider's supported capabilities.
  3. Add a DEFAULT_MODELS[ProviderType.HUGGINGFACE] entry with a sensible default model (e.g., mistralai/Mistral-7B-Instruct-v0.2).
  4. Add a PROVIDER_KEY_ATTRS[ProviderType.HUGGINGFACE] entry mapping to provider.huggingface.token / HF_TOKEN.
  5. Implement HuggingFaceChatProvider (e.g., in src/cleveragents/providers/huggingface.py) using the huggingface_hub or langchain-huggingface integration, reading the API token from HF_TOKEN.

Category

spec-alignment

Subtasks

  • Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail asserting that ProviderType.HUGGINGFACE exists in the enum
  • Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail asserting that DEFAULT_CAPABILITIES, DEFAULT_MODELS, and PROVIDER_KEY_ATTRS all contain a ProviderType.HUGGINGFACE entry
  • Add HUGGINGFACE = "huggingface" to the ProviderType enum in src/cleveragents/providers/registry.py
  • Add ProviderType.HUGGINGFACE entry to DEFAULT_CAPABILITIES with appropriate capability flags
  • Add ProviderType.HUGGINGFACE entry to DEFAULT_MODELS (e.g., mistralai/Mistral-7B-Instruct-v0.2)
  • Add ProviderType.HUGGINGFACE entry to PROVIDER_KEY_ATTRS mapping to provider.huggingface.token / HF_TOKEN
  • Implement HuggingFaceChatProvider class in src/cleveragents/providers/huggingface.py reading credentials from HF_TOKEN
  • Export HuggingFaceChatProvider from the providers package __init__.py
  • Remove @tdd_expected_fail tags from TDD scenarios and verify they pass
  • Run nox -e typecheck to confirm no type regressions
  • Run nox -e unit_tests to confirm all Behave tests pass
  • Run nox -e coverage_report to confirm coverage remains ≥ 97%
  • Run nox (all default sessions) and fix any errors

Definition of Done

  • ProviderType.HUGGINGFACE is present in the ProviderType enum in src/cleveragents/providers/registry.py
  • DEFAULT_CAPABILITIES, DEFAULT_MODELS, and PROVIDER_KEY_ATTRS all contain a ProviderType.HUGGINGFACE entry consistent with the specification (provider.huggingface.token / HF_TOKEN)
  • HuggingFaceChatProvider is implemented and exported from the providers package
  • Both TDD capture scenarios pass without @tdd_expected_fail after the fix
  • No regressions in existing provider-related tests
  • All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests, nox -e coverage_report)
  • Coverage >= 97%
  • Commit is on branch fix/spec-alignment-huggingface-provider with first line matching the Commit Message in Metadata exactly
  • PR is merged and this issue is closed

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/spec-alignment-huggingface-provider` - **Commit Message**: `fix(providers): add HUGGINGFACE to ProviderType enum and implement HuggingFaceChatProvider` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Bug Report: [spec-alignment] — Missing Hugging Face provider ### Severity Assessment - **Impact**: The Hugging Face provider is entirely absent from the `providers` module. Any user or configuration that references `provider.huggingface.token` or the `HF_TOKEN` environment variable will receive no provider resolution, causing silent failures or runtime errors when attempting to use Hugging Face-backed models. - **Likelihood**: High. The specification explicitly names Hugging Face as a supported provider with a dedicated configuration key and environment variable. Any user following the specification will encounter this gap immediately. - **Priority**: Medium ### Location - **File**: `src/cleveragents/providers/registry.py` - **Function/Class**: `ProviderType` ### Description The specification defines Hugging Face as a first-class LLM provider, documented with the configuration key `provider.huggingface.token` and the environment variable `HF_TOKEN`. However, the `providers` module contains no trace of this provider. Specifically: - The `ProviderType` enum is missing a `HUGGINGFACE` value. - `DEFAULT_CAPABILITIES` has no entry for `ProviderType.HUGGINGFACE`. - `DEFAULT_MODELS` has no entry for `ProviderType.HUGGINGFACE`. - `PROVIDER_KEY_ATTRS` has no entry mapping `ProviderType.HUGGINGFACE` to its configuration key (`provider.huggingface.token`) or environment variable (`HF_TOKEN`). - No `HuggingFaceChatProvider` class exists anywhere in the `providers` package. ### Evidence The specification mentions the `provider.huggingface.token` configuration key and the `HF_TOKEN` environment variable as the canonical way to configure the Hugging Face provider. A search of `src/cleveragents/providers/registry.py` reveals zero references to `huggingface`, `HUGGINGFACE`, or `HF_TOKEN`. ### Expected Behavior The Hugging Face provider should be fully implemented in the `providers` module, consistent with all other supported providers: 1. `ProviderType.HUGGINGFACE` enum value present in `registry.py`. 2. A corresponding entry in `DEFAULT_CAPABILITIES` describing the provider's supported capabilities. 3. A corresponding entry in `DEFAULT_MODELS` listing the default model(s) for the provider. 4. A corresponding entry in `PROVIDER_KEY_ATTRS` mapping `ProviderType.HUGGINGFACE` to `provider.huggingface.token` / `HF_TOKEN`. 5. A `HuggingFaceChatProvider` class implementing the provider interface, reading credentials from `HF_TOKEN`. ### Actual Behavior The `ProviderType` enum, `DEFAULT_CAPABILITIES`, `DEFAULT_MODELS`, and `PROVIDER_KEY_ATTRS` all lack any Hugging Face entry. The provider cannot be selected, configured, or used at runtime. ### Suggested Fix 1. Add `HUGGINGFACE = "huggingface"` to the `ProviderType` enum in `src/cleveragents/providers/registry.py`. 2. Add a `DEFAULT_CAPABILITIES[ProviderType.HUGGINGFACE]` entry reflecting the provider's supported capabilities. 3. Add a `DEFAULT_MODELS[ProviderType.HUGGINGFACE]` entry with a sensible default model (e.g., `mistralai/Mistral-7B-Instruct-v0.2`). 4. Add a `PROVIDER_KEY_ATTRS[ProviderType.HUGGINGFACE]` entry mapping to `provider.huggingface.token` / `HF_TOKEN`. 5. Implement `HuggingFaceChatProvider` (e.g., in `src/cleveragents/providers/huggingface.py`) using the `huggingface_hub` or `langchain-huggingface` integration, reading the API token from `HF_TOKEN`. ### Category spec-alignment ## Subtasks - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` asserting that `ProviderType.HUGGINGFACE` exists in the enum - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` asserting that `DEFAULT_CAPABILITIES`, `DEFAULT_MODELS`, and `PROVIDER_KEY_ATTRS` all contain a `ProviderType.HUGGINGFACE` entry - [ ] Add `HUGGINGFACE = "huggingface"` to the `ProviderType` enum in `src/cleveragents/providers/registry.py` - [ ] Add `ProviderType.HUGGINGFACE` entry to `DEFAULT_CAPABILITIES` with appropriate capability flags - [ ] Add `ProviderType.HUGGINGFACE` entry to `DEFAULT_MODELS` (e.g., `mistralai/Mistral-7B-Instruct-v0.2`) - [ ] Add `ProviderType.HUGGINGFACE` entry to `PROVIDER_KEY_ATTRS` mapping to `provider.huggingface.token` / `HF_TOKEN` - [ ] Implement `HuggingFaceChatProvider` class in `src/cleveragents/providers/huggingface.py` reading credentials from `HF_TOKEN` - [ ] Export `HuggingFaceChatProvider` from the `providers` package `__init__.py` - [ ] Remove `@tdd_expected_fail` tags from TDD scenarios and verify they pass - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox -e unit_tests` to confirm all Behave tests pass - [ ] Run `nox -e coverage_report` to confirm coverage remains ≥ 97% - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done - [ ] `ProviderType.HUGGINGFACE` is present in the `ProviderType` enum in `src/cleveragents/providers/registry.py` - [ ] `DEFAULT_CAPABILITIES`, `DEFAULT_MODELS`, and `PROVIDER_KEY_ATTRS` all contain a `ProviderType.HUGGINGFACE` entry consistent with the specification (`provider.huggingface.token` / `HF_TOKEN`) - [ ] `HuggingFaceChatProvider` is implemented and exported from the `providers` package - [ ] Both TDD capture scenarios pass without `@tdd_expected_fail` after the fix - [ ] No regressions in existing provider-related tests - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`, `nox -e coverage_report`) - [ ] Coverage >= 97% - [ ] Commit is on branch `fix/spec-alignment-huggingface-provider` with first line matching the Commit Message in Metadata exactly - [ ] PR is merged and this issue is closed --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator
freemo added this to the v3.3.0 milestone 2026-04-05 03:55:45 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Confirmed
  • MoSCoW: Should Have

Valid finding verified during batch triage.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Starting implementation on branch fix/spec-alignment-huggingface-provider.

Plan:

  • Wave 1 (parallel): Write TDD Behave scenarios + Add HUGGINGFACE to ProviderType enum + registry entries
  • Wave 2: Implement HuggingFaceChatProvider class
  • Wave 3: Export from __init__.py, remove @tdd_expected_fail tags, run quality gates

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/spec-alignment-huggingface-provider`. **Plan:** - Wave 1 (parallel): Write TDD Behave scenarios + Add `HUGGINGFACE` to `ProviderType` enum + registry entries - Wave 2: Implement `HuggingFaceChatProvider` class - Wave 3: Export from `__init__.py`, remove `@tdd_expected_fail` tags, run quality gates --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#362 Epic: Security & Safety Hardening
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3018
No description provided.