Metadata-Version: 2.4
Name: simplegroqai
Version: 0.0.1
Summary: A tiny beginner-friendly Python package for calling Groq AI with one function.
Author: Your Name
License: MIT License
        
        Copyright (c) 2026 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/your-username/simplegroqai
Project-URL: Repository, https://github.com/your-username/simplegroqai
Project-URL: Issues, https://github.com/your-username/simplegroqai/issues
Keywords: groq,ai,llm,chatbot,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: groq
Requires-Dist: python-dotenv
Dynamic: license-file

# simplegroqai

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

```python
ai("Your question here")
```

It uses the [Groq Python SDK](https://pypi.org/project/groq/) internally and the model:

```text
llama-3.1-8b-instant
```

## Folder Structure

```text
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:

```bash
pip install simplegroqai
```

## Usage

### Example 1: Pass the API Key Directly

```python
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:

```bash
export GROQ_API_KEY="your_key"
```

Then use the package without passing the key directly:

```python
from simplegroqai import ai

print(ai("Explain AI"))
```

On Windows PowerShell, set the environment variable like this:

```powershell
$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

```bash
python -m venv .venv
```

### 2. Activate the Virtual Environment

macOS/Linux:

```bash
source .venv/bin/activate
```

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

### 3. Install Dependencies

Install the package locally in editable mode:

```bash
pip install -e .
```

Install build and upload tools:

```bash
pip install build twine
```

## Build the Package

Run:

```bash
python -m build
```

This creates distribution files inside the `dist/` folder.

## Upload to PyPI

Before uploading, create an account on [PyPI](https://pypi.org/) and create an API token.

Then run:

```bash
python -m twine upload dist/*
```

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

For token-based upload, use:

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

## Full Publishing Command List

```bash
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:

```toml
version = "0.1.1"
```

Then run:

```bash
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`

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

from .main import ai

__all__ = ["ai"]
```

`simplegroqai/main.py`

```python
"""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.
