Skip to content

gemini_ai_demo

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

gemini_ai_demo

README.md

Enrich data with Gemini and Parallel Web Search

Have a company name and website, but need the missing details? The enrichment notebook shows how to research a company with Gemini and Parallel, then turn the answer into a record with sources attached.

It follows one company from input to result, then reuses the same code for a person and a product. You'll use Google's native parallel_ai_search tool throughout. Read about the Parallel and Google Cloud integration.

Run the notebook

From the repository root:

cd python-recipes/gemini_ai_demo
uv sync --frozen --extra notebook
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
gcloud auth application-default login
uv run --frozen --extra notebook jupyter notebook gemini_search_enrichment.ipynb

Your Google Cloud project needs billing and the Vertex AI API enabled. For Parallel, enter an API key at the notebook's hidden prompt, or leave it blank if your project has a Marketplace grounding subscription. You can also set PARALLEL_API_KEY before launching Jupyter. A supplied key takes precedence over Marketplace billing.

The notebook uses google-genai directly and is self-contained. It checks record identity, citation URLs, and coverage of populated fields. Review the sources before using the facts. Google generation and grounding, plus Parallel search, may incur charges; see billing details.

Check the code

uv run --frozen --extra dev pytest tests/ -q

The tests exercise the notebook's local checks and the separate REST client. They don't make API calls. To check the live integration, restart the notebook kernel and run all cells with your Google credentials and Parallel access.

Other examples

The older quickstart, command-line demo, and introductory tutorial use the local GroundedGeminiClient REST wrapper. The enrichment notebook doesn't depend on that wrapper.

REST client setup and reference

Prerequisites

  1. Google Cloud Project with billing enabled
  2. Vertex AI API enabled in your project
  3. Parallel auth configured via one of:
  4. Python 3.10+ and uv package manager
  5. Google Cloud authentication configured

See the Parallel + Vertex AI integration docs for a comparison of the two modes.

Quick Start

1. Clone and Setup

cd gemini_ai_demo

# Install dependencies using uv
uv sync

# Or install with pip
pip install -e .

2. Configure Authentication

# Authenticate with Google Cloud
gcloud auth application-default login

# Set your project
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# Optional: only if using Bring Your Own Key (BYOK) instead of a
# Google Cloud Marketplace subscription.
# Get a key from https://platform.parallel.ai
# export PARALLEL_API_KEY="your-parallel-api-key"

3. Validate Setup

# Check that everything is configured correctly
python demo.py --check

4. Try the Quickstart

The fastest way to get started is with our minimal example:

python quickstart.py

Or in Python:

from gemini_parallel import GroundedGeminiClient

client = GroundedGeminiClient()
response = client.generate("Who won the most recent Super Bowl?")
print(response.text)

5. Run the Full Demo

# Run with sample questions (shows grounded vs ungrounded comparison)
python demo.py

# Run more sample questions
python demo.py --num 5

# Interactive mode - ask your own questions
python demo.py --interactive

# Use a different model
python demo.py --model gemini-2.5-flash

# Show full responses (not truncated)
python demo.py --full

The demo compares responses with and without Parallel grounding for questions about recent events, showing how grounding provides access to real-time web information.

6. Interactive Tutorial

For a step-by-step learning experience, open the Jupyter notebook:

# Install notebook dependencies
pip install -e ".[notebook]"
# Or with uv
uv sync --extra notebook

# Launch the tutorial
jupyter notebook tutorial.ipynb

Usage

Basic Usage (Google Cloud Marketplace)

When your GCP project has a Parallel Web Search Marketplace subscription, no API key is needed.

from gemini_parallel import GroundedGeminiClient

# Initialize the client (Marketplace mode)
client = GroundedGeminiClient(
    project_id="your-project-id",
)

# Generate a grounded response
response = client.generate(
    prompt="Who won the most recent FIFA World Cup?",
    model_id="gemini-2.0-flash",
)

print(response.text)
print(f"Sources: {[s.uri for s in response.sources]}")

Basic Usage (Bring Your Own Key)

Pass parallel_api_key (or set PARALLEL_API_KEY) to authenticate with a Parallel key instead.

from gemini_parallel import GroundedGeminiClient

client = GroundedGeminiClient(
    project_id="your-project-id",
    parallel_api_key="your-parallel-api-key",
)

response = client.generate("Who won the most recent FIFA World Cup?")
print(response.text)

Note: If both a Marketplace subscription and an API key are present, the API key takes precedence.

With Custom Configuration

from gemini_parallel import GroundedGeminiClient, GroundingConfig

# Configure grounding options. Leave api_key unset for Marketplace mode,
# or pass a key for BYOK.
config = GroundingConfig(
    # api_key="your-parallel-api-key",  # Uncomment for BYOK
    max_results=5,                    # Max search results (1-20)
    include_domains=["www.example.com"],  # Only these domains
    exclude_domains=[],         # Exclude these domains
)

client = GroundedGeminiClient(
    project_id="your-project-id",
    grounding_config=config,
)

response = client.generate(
    prompt="What is the latest news about AI regulation?",
    temperature=0.2,
    system_instruction="Provide a concise summary with key dates.",
)

Validate Setup

Before running your code, you can validate that all credentials are configured correctly:

from gemini_parallel import validate_setup

status = validate_setup()
print(status)

if not status.is_valid:
    # status shows exactly what's missing and how to fix it
    exit(1)

Convenience Function

from gemini_parallel import generate_grounded_response

# Marketplace
response = generate_grounded_response(
    prompt="What are the latest breakthroughs in quantum computing?",
    project_id="your-project",
)

# BYOK
response = generate_grounded_response(
    prompt="What are the latest breakthroughs in quantum computing?",
    project_id="your-project",
    parallel_api_key="your-parallel-api-key",
)

Configuration

Environment Variables

Variable Description Required
GOOGLE_CLOUD_PROJECT Google Cloud project ID Yes
PARALLEL_API_KEY Parallel API key. Only required for Bring Your Own Key (BYOK) mode; leave unset when using a Google Cloud Marketplace subscription No
GOOGLE_CLOUD_LOCATION GCP region (default: us-central1) No
GOOGLE_APPLICATION_CREDENTIALS Path to service account JSON No

GroundingConfig Options

Parameter Description Default Range
api_key Parallel API key for BYOK mode. Leave unset for Marketplace. None -
max_results Max search results 10 1-20
max_chars_per_result Max chars per result excerpt 30,000 1,000-100,000
max_chars_total Max total chars from all excerpts 100,000 1,000-1,000,000
include_domains Only search these domains None Up to 10
exclude_domains Exclude these domains None Up to 10

Supported Models

See the official documentation for the latest list.

Gemini 3 (Preview)

  • gemini-3.0-flash
  • gemini-3.0-pro
  • gemini-3.0-pro-image

Gemini 2.5

  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

Gemini 2.0

  • gemini-2.0-flash

The default model is gemini-2.5-flash.

API Response

The GroundedResponse object contains:

@dataclass
class GroundedResponse:
    text: str                           # Generated response text
    sources: list[GroundingSource]      # List of source URLs and titles
    web_search_queries: list[str]       # Queries executed by the model
    raw_response: dict                  # Full API response for debugging
    grounding_supports: list[dict]      # Detailed grounding information

Project Structure

gemini_ai_demo/
├── src/gemini_parallel/     # Source code
│   ├── __init__.py         # Package exports
│   └── client.py           # Main client implementation
├── tests/                   # Test suite
│   ├── conftest.py         # Test fixtures
│   └── test_client.py      # Unit tests
├── quickstart.py           # Minimal example (~15 lines)
├── demo.py                  # Full demo script with comparisons
├── tutorial.ipynb          # Interactive Jupyter tutorial
├── gemini_search_enrichment.ipynb  # Cookbook: company, people & product enrichment
├── pyproject.toml          # Project configuration
├── README.md               # This file
├── .env.example            # Environment variable template
└── .gitignore              # Git ignore patterns

Pricing

Using Grounding with Parallel incurs the following charges:

Component Description
Gemini tokens Prompt, thinking, and output tokens (Vertex AI pricing)
Grounding Vertex AI grounding charges
Parallel Search Per-query pricing (Parallel pricing)

Note: Input tokens provided by Parallel are not charged extra.

Quota

The default quota is 200 prompts per minute. To increase rate limits, contact your Google account team (Marketplace) or support@parallel.ai (BYOK) with your use case.

Troubleshooting

Common Issues

  1. Authentication Error

    gcloud auth application-default login

  2. API Not Enabled

    gcloud services enable aiplatform.googleapis.com

  3. Marketplace subscription missing

  4. Invalid API Key (BYOK only)

  5. Rate Limiting

    • Default quota is 200 requests/minute
    • Contact support for higher limits

Logs and Debugging

# Access raw API response for debugging
response = client.generate("...")
print(response.raw_response)

# Check grounding supports for citation details
print(response.grounding_supports)

Related Resources

License

See repository root for license information.

Terms of Service

Your use of Parallel requires Google Cloud to send certain Customer Data to Parallel for processing. Your use of the Parallel service is governed by: