groqd/README.md

<p align="center">
  <img src="assets/groqd-chatstar-512.svg" alt="groqd" width="180" />
</p>

<h1 align="center">groqd</h1>

<p align="center">
  A Home Assistant custom integration for Groq Cloud with memory, web search, and link ingestion.
</p>

<p align="center">
  <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=sudoxreboot&repository=groqd&category=integration">
    <img src="https://my.home-assistant.io/badges/hacs_repository.svg" alt="Add Repository to HACS" />
  </a>
  <a href="https://my.home-assistant.io/redirect/config_flow_start/?domain=groqd">
    <img src="https://my.home-assistant.io/badges/config_flow_start.svg" alt="Configure integration" />
  </a>
</p>

---

## Features
- Multiple instances (different models, personalities, and settings)
- Persistent memory (device/user/global scopes)
- Tool calling via Home Assistant LLM API
- Optional web search via SearxNG
- Auto-fetch and ingest URLs from user messages
- Rich generation controls (temperature, top_p, penalties, max tokens, response format)

## Install (HACS)
1. **Add** this repository to HACS (Integration):

   [![Add Repository to HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=sudoxreboot&repository=groqd&category=integration)

   Or copy this URL into HACS → Custom repositories:

   `https://github.com/sudoxreboot/groqd`

2. Install `groqd` in HACS.
3. Restart Home Assistant.

## Configure
- **Click to add the integration:**

  [![Configure integration](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=groqd)

- Or go to **Settings → Devices & Services → + Add Integration** and search for `groqd`.

## Quick Start
- Create a new groqd entry.
- Set your Groq API key.
- Pick a model (default: `meta-llama/llama-4-scout-17b-16e-instruct`).
- Set a personality prompt if you want tone/style changes.

## Options
Open **groqd → Options** to configure:
- Memory scope: `device`, `user`, `global`, or `conversation`
- Context window size
- Max tokens, temperature, top_p, penalties
- Response format (`text` / `json_object`)
- SearxNG (enable + URL + language + safe search)
- Auto-fetch URLs in user messages
- Time format (12h / 24h)

## Notes
- TTS/STT are handled by Home Assistant and other integrations.
- Web search is optional and only used if enabled.
- Auto-fetch pulls page text and injects it into the prompt for better grounding.

## Support
Open issues or requests at: https://github.com/sudoxreboot/groqd/issues