Metadata-Version: 2.4
Name: gemini-starter-agent
Version: 0.1.4
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.

## 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
from dotenv import load_dotenv
from agents import Agent, Runner, RunConfig, OpenAIChatCompletionsModel, set_tracing_disabled
from openai import AsyncOpenAI

load_dotenv()

set_tracing_disabled(True)

client: AsyncOpenAI = AsyncOpenAI(api_key=os.getenv("API_KEY"), base_url=os.getenv("BASE_URL"))
model: OpenAIChatCompletionsModel = OpenAIChatCompletionsModel(os.getenv("MODEL"), client)

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

async def main() -> None:
    prompt = "What is Agentic AI? The output format should be in haiku"
    result = await Runner.run(agent, prompt, run_config=RunConfig(model))
    print(result.final_output)


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)
