Metadata-Version: 2.4
Name: nucleusiq-groq
Version: 0.1.0b1
Summary: Groq inference provider for the NucleusIQ AI agent framework (official groq Python SDK).
Project-URL: Homepage, https://github.com/nucleusbox/NucleusIQ
Project-URL: Repository, https://github.com/nucleusbox/NucleusIQ
Project-URL: Issues, https://github.com/nucleusbox/NucleusIQ/issues
Author-email: Nucleusbox <info@nucleusbox.com>
License: MIT
Keywords: AI,agents,groq,llama,nucleusiq,openai-compatible
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4.0,>=3.10
Requires-Dist: groq<2.0,>=1.2.0
Requires-Dist: nucleusiq>=0.7.9
Description-Content-Type: text/markdown

# nucleusiq-groq

**Groq inference provider** for [NucleusIQ](https://github.com/nucleusbox/NucleusIQ): Chat Completions via Groq’s **OpenAI-compatible** API, using Groq’s official **`groq`** Python SDK (`AsyncGroq` / `Groq`).

**Status:** **0.1.0b1** (public **beta** / pre-release). Requires **`nucleusiq>=0.7.9`**.

Design, phased roadmap (Phase A vs B), and API caveats: [`docs/design/GROQ_PROVIDER.md`](../../../../docs/design/GROQ_PROVIDER.md) (repo root).

---

## Install

**PyPI (when published):**

```bash
pip install nucleusiq nucleusiq-groq
```

**Monorepo (editable):**

```bash
cd src/providers/inference/groq
uv sync --group dev
```

Core is pulled via `[tool.uv.sources]` as an editable path dependency; for `pip`-only local installs, install `nucleusiq` from `src/nucleusiq` first, then this package.

---

## Configuration

| Variable | Purpose |
|----------|---------|
| **`GROQ_API_KEY`** | Required. Groq API key. |
| **`GROQ_MODEL`** | Optional. Default for chat/tool examples: `llama-3.3-70b-versatile`. |
| **`GROQ_MODEL_STRUCTURED`** | Optional. Model for **`json_schema`** structured output (example `05` defaults to `openai/gpt-oss-20b` if unset). |

Unsupported Chat Completions fields (e.g. `logit_bias`, `messages[].name`) are stripped or rejected at the wire layer; see the design doc.

---

## Usage

```python
import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.agents.task import Task
from nucleusiq.prompts.zero_shot import ZeroShotPrompt
from nucleusiq_groq import BaseGroq, GroqLLMParams

async def main() -> None:
    llm = BaseGroq(model_name="llama-3.3-70b-versatile", async_mode=True)
    agent = Agent(
        name="demo",
        prompt=ZeroShotPrompt(),
        llm=llm,
        config=AgentConfig(
            execution_mode=ExecutionMode.DIRECT,
            llm_params=GroqLLMParams(temperature=0.2),
        ),
    )
    await agent.initialize()
    result = await agent.execute(Task(id="1", objective="Capital of France in one short phrase."))
    print(result.output)

asyncio.run(main())
```

---

## Phase A (this beta)

- **`BaseGroq`** — `call` / `call_stream`, tool calling, structured output (`response_format` / Pydantic).
- **`GroqLLMParams`** — typed, `extra="forbid"`; merges into provider calls.
- **Local function tools** — OpenAI-style tool JSON; assistant `tool_calls` normalized for Groq before each request.
- **Retries** — rate-limit and transient errors with exponential backoff; **429** + **`Retry-After`** on non-stream and **streaming open**; errors mapped to NucleusIQ `LLMError` types.
- **Hosted tool IDs** — `nucleusiq_groq.tools.GROQ_COMPOUND_HOSTED_TOOL_IDS` / `GROQ_GPT_OSS_HOSTED_TOOL_IDS` mirror [Groq built-in docs](https://console.groq.com/docs/tool-use/built-in-tools) for reference only (**not** wired into `call` yet).

**Groq constraints you should respect:** per [Structured outputs](https://console.groq.com/docs/structured-outputs), **streaming** and **tool use** are not currently supported **with** Structured Outputs on the same request — use non-streaming `call` for `response_format`, or skip structured output when streaming / using tools.

**Not in Phase A:** automatic pass-through for **`compound_custom`**, Groq **Responses API**, and **remote MCP** (see design doc Phase B).

**Integration tests (optional):** from `src/providers/inference/groq`, with **`GROQ_API_KEY`** in the environment:

```bash
uv run pytest tests/integration -m integration
```

Default `pytest` / CI uses **`-m "not integration"`** so live calls are optional.

---

## Examples

Runnable agents (real API): [`examples/README.md`](examples/README.md).

```bash
cd src/providers/inference/groq
uv run python examples/agents/01_groq_direct.py
```

---

## Development

From this directory:

```bash
uv sync --group dev
uvx ruff check nucleusiq_groq tests examples
uvx pyrefly check
uv run pytest
```

---

## License

MIT — same as the NucleusIQ monorepo.
