Metadata-Version: 2.4
Name: gemini-starter-agent
Version: 0.1.3
Summary: A CLI tool to bootstrap OpenAI Agents SDK projects with Gemini, Groq, or xAI (Grok) using UV.
Author: Marjan Ahmed
Author-email: marjanahmed.dev@gmail.com
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: python-dotenv
Requires-Dist: InquirerPy
Requires-Dist: toml
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Gemini Starter Agent

[![Python](https://img.shields.io/badge/python-3.13+-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE.md)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/gemini-starter-agent?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BRIGHTGREEN&left_text=downloads)](https://pepy.tech/projects/gemini-starter-agent)

Gemini Starter Agent is a Python CLI that scaffolds AI agent projects using the OpenAI Agents SDK with OpenAI-compatible providers. It currently supports Gemini, Groq, and xAI (Grok), creates a UV-managed project, installs runtime dependencies, and generates a ready-to-run agent template.

## Features

- Bootstrap a new AI agent project from one CLI command.
- Choose Gemini, Groq, or xAI (Grok) during setup.
- Select a default model or enter a custom OpenAI-compatible model name.
- Create a new project folder or write into the current directory with `.`.
- Generate `.env`, `src/<package>/main.py`, and `pyproject.toml` script entries.
- Install `openai-agents` and `python-dotenv` into the generated project with UV.
- Friendly error messages for common API issues (invalid key, no credits, rate limits, etc.).

## Installation

```bash
pip install gemini-starter-agent
```

The package installs this console command:

```bash
gemini-starter-agent
```

## Usage

Create a new project folder:

```bash
gemini-starter-agent my-agent
```

Use the current directory and skip the project-name prompt:

```bash
gemini-starter-agent .
```

Run interactively and enter the project name when prompted:

```bash
gemini-starter-agent
```

If the current directory is not empty and you use `.`, the CLI asks for confirmation before writing files.

## CLI Prompts

Depending on the command, you will be asked for:

- Project name, unless passed as `my-agent` or `.`.
- Provider: `Gemini`, `Groq`, or `xAI`.
- Provider API key.
- Model selection or a custom model.
- Agent name.
- Agent instructions/purpose.

## Provider Defaults

### Gemini

Base URL:

```text
https://generativelanguage.googleapis.com/v1beta/openai/
```

Models:

- `gemini-2.0-flash`
- `gemini-2.5-flash`
- Custom model

### Groq

Base URL:

```text
https://api.groq.com/openai/v1
```

Models:

- `llama-3.1-8b-instant`
- `llama-3.3-70b-versatile`
- `openai/gpt-oss-20b`
- Custom model

### xAI (Grok)

Base URL:

```text
https://api.x.ai/v1
```

Models:

- `grok-4`
- `grok-4-mini`
- `grok-4.5`
- Custom model

## Generated Project Structure

```text
your-project-name/
|-- src/
|   `-- your_project_name/
|       |-- __init__.py
|       `-- main.py
|-- .env
|-- pyproject.toml
`-- uv.lock
```

When you run `openai-compatible-agent .`, these files are created directly in the current directory instead of a nested folder.

## Generated Environment Variables

Example Groq `.env`:

```env
PROVIDER=groq
API_KEY=your_api_key_here
MODEL=llama-3.3-70b-versatile
BASE_URL=https://api.groq.com/openai/v1
```

Example Gemini `.env`:

```env
PROVIDER=gemini
API_KEY=your_api_key_here
MODEL=gemini-2.5-flash
BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
```

Example xAI `.env`:

```env
PROVIDER=xai
API_KEY=your_api_key_here
MODEL=grok-4
BASE_URL=https://api.x.ai/v1
```

## Running Your Generated Agent

If you created a new folder, change into it:

```bash
cd my-agent
```

Run the script printed by the CLI:

```bash
uv run helpful-assistant
```

The CLI also adds a project-prefixed script name, for example:

```bash
uv run my-agent-helpful-assistant
```

## Example Generated `main.py`

```python
import asyncio
import os
import sys
from dotenv import load_dotenv
from agents import Agent, Runner, RunConfig, OpenAIChatCompletionsModel, set_tracing_disabled
from openai import AsyncOpenAI, AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, APIConnectionError, APITimeoutError

load_dotenv()

PROVIDER = os.getenv("PROVIDER", "openai-compatible")
MODEL = os.getenv("MODEL")
API_KEY = os.getenv("API_KEY")
BASE_URL = os.getenv("BASE_URL")

if not API_KEY:
    print("ERROR: API_KEY is missing. Add it to your .env file.")
    sys.exit(1)
if not MODEL:
    print("ERROR: MODEL is missing. Add it to your .env file.")
    sys.exit(1)
if not BASE_URL:
    print("ERROR: BASE_URL is missing. Add it to your .env file.")
    sys.exit(1)

set_tracing_disabled(True)

client: AsyncOpenAI = AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL)
model: OpenAIChatCompletionsModel = OpenAIChatCompletionsModel(MODEL, client)

agent: Agent = Agent(
    name="Helpful Assistant",
    instructions="You're a helpful assistant, help user with any query",
    model=model,
)

PROVIDER_HINTS = {
    "gemini": "Get your key at https://aistudio.google.com/apikey",
    "groq": "Get your key at https://console.groq.com/keys",
    "xai": "Get your key at https://console.x.ai/team/default/api-keys",
}

async def main() -> None:
    prompt = "What is Agentic AI? The output format should be in haiku"
    try:
        result = await Runner.run(agent, prompt, run_config=RunConfig(model))
        print(f"Provider: {PROVIDER}")
        print(result.final_output)
    except AuthenticationError:
        hint = PROVIDER_HINTS.get(PROVIDER, "")
        print(f"\nERROR: Invalid API key for {PROVIDER}.")
        if hint:
            print(f"  -> {hint}")
        print("  -> Check your .env file and make sure the API_KEY is correct.")
        sys.exit(1)
    except PermissionDeniedError as e:
        msg = str(e)
        if "credit" in msg.lower() or "403" in msg:
            print(f"\nERROR: Your {PROVIDER} account has no credits or insufficient permissions.")
            print("  -> Add credits or check your account billing.")
        else:
            print(f"\nERROR: Permission denied: {msg}")
        sys.exit(1)
    except RateLimitError:
        print(f"\nERROR: Rate limit exceeded for {PROVIDER}.")
        print("  -> You're sending too many requests. Wait a moment and try again.")
        sys.exit(1)
    except NotFoundError:
        print(f"\nERROR: Model '{MODEL}' not found on {PROVIDER}.")
        print("  -> Check the model name in your .env file.")
        sys.exit(1)
    except APIConnectionError:
        print(f"\nERROR: Could not connect to {PROVIDER} API at {BASE_URL}.")
        print("  -> Check your internet connection.")
        sys.exit(1)
    except APITimeoutError:
        print(f"\nERROR: Request to {PROVIDER} API timed out.")
        print("  -> The server took too long to respond. Try again later.")
        sys.exit(1)
    except Exception as e:
        print(f"\nERROR: Unexpected error: {e}")
        sys.exit(1)


def start():
    asyncio.run(main())
```

## Local Development

```bash
pip install -e .
python -m py_compile gemini_starter_agent/main.py
gemini-starter-agent .
```

Build release artifacts locally:

```bash
python setup.py sdist bdist_wheel
```

## Notes

- `uv` must be installed and available on `PATH` because the CLI runs `uv init`, `uv venv`, and `uv add`.
- Do not commit generated `.env` files or real provider API keys.

## License

This project is licensed under the MIT License. See [LICENSE.md](./LICENSE.md).

## Author

**Marjan Ahmed**

- Email: [marjanahmed.dev@gmail.com](mailto:marjanahmed.dev@gmail.com)
- GitHub: [https://github.com/marjan-ahmed](https://github.com/marjan-ahmed)
