Development

Use this page as a contributor map for the Groq integration source layout, runtime shape, test harness, and safety rules.

Contents

• Runtime shape
• Repository layout
• Test harness
• CI parity checks
• Development notes
• Related pages

Runtime shape

The integration creates one Groq account config entry and one or more service subentries. Service subentries determine which Home Assistant platforms are set up and which Groq response services have usable defaults.

flowchart TD
    A["Config flow"] --> B["Groq account entry"]
    B --> C["Service subentries"]
    C --> D["Runtime data"]
    D --> E["Groq API client"]
    D --> F["Conversation entity"]
    D --> G["AI Task entity"]
    D --> H["STT entity"]
    D --> I["TTS entity"]
    D --> J["Response services"]
    E --> K["Groq cloud APIs"]

Loading

Repository layout

Integration source lives in custom_components/groq/.

Important modules:

• config_flow.py: account setup, reauthentication, options, and service subentry flows
• api.py: shared async Groq API client
• model_registry.py: model capability discovery and fallback metadata
• feature_registry.py: feature definitions
• services.py: Home Assistant response services
• conversation.py: Text Generation and Assist support
• ai_task.py: AI Task support
• stt.py: Speech-to-Text entity
• tts.py: Text-to-Speech entity and audio processing
• tts_engine.py: TTS API adapter
• diagnostics.py: redacted diagnostics

Tests live under tests/components/groq/.

Test harness

Tests run in the Home Assistant Docker-based harness:

scripts/test

Run a targeted test command:

scripts/test python -m pytest tests/components/groq -q

CI parity checks

scripts/test python scripts/validate_quality_scale.py
scripts/test python scripts/importtime_profile.py --strict-integration-warnings
scripts/test python -m pytest --cov=custom_components.groq --cov-report=term-missing --cov-fail-under=80 -q

Development notes

• Keep network calls async and non-blocking.
• Do not log API keys, prompts, image bytes, audio bytes, or sensitive Home Assistant data.
• Prefer Home Assistant-native entity surfaces where they exist: conversation, ai_task, stt, and tts.
• Use response services for one-shot operations that return generated data.
• Add tests for config validation, network error paths, model gating, response services, and service subentry behavior.

Related pages

• Account and Service Setup
• Text Generation
• Troubleshooting