simplegroqai 0.0.1

A tiny beginner-friendly Python package for calling Groq AI with one function.

simplegroqai

simplegroqai is a tiny beginner-friendly Python package that gives you one simple function:

ai("Your question here")

It uses the Groq Python SDK internally and the model:

llama-3.1-8b-instant

Folder Structure

simplegroqai/
├── simplegroqai/
│   ├── __init__.py
│   └── main.py
├── LICENSE
├── README.md
└── pyproject.toml

Installation After Publishing

After this package is published to PyPI, users can install it with:

pip install simplegroqai

Usage

Example 1: Pass the API Key Directly

from simplegroqai import ai

print(ai("What is Python?", api_key="YOUR_KEY"))

Example 2: Use an Environment Variable

Set your Groq API key in the terminal:

export GROQ_API_KEY="your_key"

Then use the package without passing the key directly:

from simplegroqai import ai

print(ai("Explain AI"))

On Windows PowerShell, set the environment variable like this:

$env:GROQ_API_KEY="your_key"

Local Development Setup

Follow these steps if you are creating, testing, building, or publishing the package yourself.

1. Create a Virtual Environment

python -m venv .venv

2. Activate the Virtual Environment

macOS/Linux:

source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

3. Install Dependencies

Install the package locally in editable mode:

pip install -e .

Install build and upload tools:

pip install build twine

Build the Package

Run:

python -m build

This creates distribution files inside the dist/ folder.

Upload to PyPI

Before uploading, create an account on PyPI and create an API token.

Then run:

python -m twine upload dist/*

Twine will ask for your PyPI username and password/token.

For token-based upload, use:

username: __token__
password: your-pypi-api-token

Full Publishing Command List

python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install build twine
python -m build
python -m twine upload dist/*

Updating Package Versions Later

To release a new version:

1. Open pyproject.toml.
2. Change the version number.
3. Build the package again.
4. Upload the new build to PyPI.

Example:

version = "0.1.1"

Then run:

python -m build
python -m twine upload dist/*

PyPI does not allow uploading the same version twice, so every new release needs a new version number.

Error Handling

If no API key is provided and GROQ_API_KEY is not set, simplegroqai raises a clear ValueError.

If the Groq API request fails, simplegroqai raises a RuntimeError with the original error message.

Source Code

simplegroqai/__init__.py

"""Simple public interface for the simplegroqai package."""

from .main import ai

__all__ = ["ai"]

simplegroqai/main.py

"""Core functionality for simplegroqai."""

import os
from typing import Optional

from groq import Groq


def ai(q: str, api_key: Optional[str] = None) -> str:
    """Send a prompt to Groq and return the AI response text.

    Args:
        q: The user prompt/question to send to the AI model.
        api_key: Optional Groq API key. If not provided, the function reads
            the GROQ_API_KEY environment variable.

    Returns:
        The text content returned by the Groq chat completion API.

    Raises:
        ValueError: If the prompt is empty or no API key is available.
        RuntimeError: If the Groq API request fails.
    """
    # Validate the prompt early so users get a clear, beginner-friendly error.
    if not isinstance(q, str) or not q.strip():
        raise ValueError("Prompt q must be a non-empty string.")

    # Prefer an explicitly passed key, then fall back to the environment.
    groq_api_key = api_key or os.getenv("GROQ_API_KEY")

    # Never hardcode API keys. Ask the user to pass one or set GROQ_API_KEY.
    if not groq_api_key:
        raise ValueError(
            "Groq API key is missing. Pass api_key='YOUR_KEY' or set "
            "the GROQ_API_KEY environment variable."
        )

    try:
        # Create the Groq client with the resolved API key.
        client = Groq(api_key=groq_api_key)

        # Send the user's prompt to the requested Groq model.
        response = client.chat.completions.create(
            model="llama-3.1-8b-instant",
            messages=[
                {"role": "user", "content": q}
            ],
            max_tokens=3000
        )

        # Return only the assistant's response text for a simple API.
        return response.choices[0].message.content
    except Exception as exc:
        # Wrap SDK/network/API failures in a clear error for library users.
        raise RuntimeError(f"Groq API request failed: {exc}") from exc

License

This project is licensed under the MIT License.