Metadata-Version: 2.4
Name: waken-groq
Version: 0.1.0
Summary: Groq Target adapter for Waken — routes waken Events to Groq's fast inference API.
Project-URL: Homepage, https://github.com/WakenHQ/waken-groq
Project-URL: Repository, https://github.com/WakenHQ/waken-groq
Project-URL: Issues, https://github.com/WakenHQ/waken-groq/issues
Author: Waken contributors
License: MIT
License-File: LICENSE
Keywords: agents,ai,groq,waken
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: groq>=0.9.0
Requires-Dist: waken>=0.1.1
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# waken-groq

[![CI](https://github.com/WakenHQ/waken-groq/actions/workflows/ci.yml/badge.svg)](https://github.com/WakenHQ/waken-groq/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/WakenHQ/waken-groq/blob/main/LICENSE)

A Groq [`Target`](https://github.com/WakenHQ/waken) adapter for
[Waken](https://github.com/WakenHQ/waken) — "nginx for AI agents." Routes
waken `Event`s to Groq's chat completions API and returns the result as a
waken `Response`.

Groq's API is shaped like OpenAI's Chat Completions API — its differentiator
is inference *speed* (custom LPU hardware), not a different way of talking
to it.

## Install

```bash
pip install waken-groq
```

## Usage

```python
from waken import Runtime
from waken_groq import GroqAdapter

runtime = Runtime()
runtime.target("groq", GroqAdapter())
runtime.run()
```

`GroqAdapter` reads `GROQ_API_KEY` from the environment — that's the `groq`
SDK's own convention (see `AsyncGroq()`), nothing waken-specific. Pass
`api_key=...` (or any other `AsyncGroq` keyword) to override:

```python
runtime.target("groq", GroqAdapter(model="llama-3.1-8b-instant", api_key="..."))
```

## Sessions

Groq's chat completions API is stateless per call — there is no
server-side session or thread, the caller resends the full conversation
every time. So `GroqAdapter` maps a waken `session_id` to a plain list of
chat messages that it grows and resends on every turn. This history lives
only in the adapter's process memory — it is never persisted, and does not
survive a process restart. An `Event` with no `session_id` sends a single
one-off message and is never stored.

## Development

```bash
git clone https://github.com/WakenHQ/waken-groq
cd waken-groq
pip install -e ".[dev]"
pytest
```

Tests mock `groq.AsyncGroq` entirely — no API key or network access needed
to run the suite.

## License

[MIT](https://github.com/WakenHQ/waken-groq/blob/main/LICENSE)
