zhongwei/gh-dnvriend-gemini-google-search-tool-plugins-gemini-google-search-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:23:20 +08:00
commit 611a646dde
6 changed files with 574 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "gemini-google-search-tool",
"description": "Query Gemini with Google Search grounding for real-time web information",
"version": "0.1.0",
"author": {
"name": "Dennis Vriend"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# gemini-google-search-tool
Query Gemini with Google Search grounding for real-time web information

36
commands/completion.md Normal file
View File

@@ -0,0 +1,36 @@
---
description: Generate shell completion scripts
argument-hint: shell
---
Generate shell completion script for bash, zsh, or fish.
## Usage
```bash
gemini-google-search-tool completion {bash|zsh|fish}
```
## Arguments
- `SHELL`: Shell type (bash, zsh, or fish)
## Examples
```bash
# Generate bash completion
gemini-google-search-tool completion bash
# Install bash completion
eval "$(gemini-google-search-tool completion bash)"
# Install zsh completion
eval "$(gemini-google-search-tool completion zsh)"
# Install fish completion
gemini-google-search-tool completion fish > ~/.config/fish/completions/gemini-google-search-tool.fish
```
## Output
Shell-specific completion script to stdout.

47
commands/query.md Normal file
View File

@@ -0,0 +1,47 @@
---
description: Query Gemini with Google Search grounding
argument-hint: prompt
---
Query Gemini with Google Search grounding for real-time web information with automatic citations.
## Usage
```bash
gemini-google-search-tool query "PROMPT" [OPTIONS]
```
## Arguments
- `PROMPT`: Search query (required, or use `--stdin`)
- `--stdin` / `-s`: Read prompt from stdin
- `--add-citations`: Add inline citation links to response
- `--pro`: Use gemini-2.5-pro (default: gemini-2.5-flash)
- `--text` / `-t`: Output markdown format (default: JSON)
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
## Examples
```bash
# Basic query
gemini-google-search-tool query "Who won euro 2024?"
# With inline citations
gemini-google-search-tool query "Latest AI news" --add-citations
# From stdin
echo "Climate change" | gemini-google-search-tool query --stdin
# Pro model with debug output
gemini-google-search-tool query "Quantum computing" --pro -vv
```
## Output
**JSON (default):**
- `response_text`: AI response with grounding
- `citations`: Array of {index, uri, title}
- `grounding_metadata`: Search queries and supports (with `-vv`)
**Markdown (`--text`):**
- Response text followed by citations list

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:dnvriend/gemini-google-search-tool:plugins/gemini-google-search-tool",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "f8b93f67d0346cc2a4f9063ddaf8447299bd8e92",
"treeHash": "b36cdadd80230dfbc26fcee9151031fdba993386742011c204a985108e2eeef7",
"generatedAt": "2025-11-28T10:16:35.767029Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "gemini-google-search-tool",
"description": "Query Gemini with Google Search grounding for real-time web information",
"version": "0.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "66f333fe523f8c453940f8bf628a840402bf98ee69bbf295bcdd513cb6ebdd98"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "33bae54e9f8891328f1e5cb32e901599e3aa64ea15b4788eb5d63ec35479bf6e"
},
{
"path": "commands/completion.md",
"sha256": "7224073f0f3a54fde58cd3b93b889cf588ccd3bb5a3459064631b1e8e4c760d9"
},
{
"path": "commands/query.md",
"sha256": "e1900715df175185fea9f4f209c4da9a50ce760547002c1df77d90672c4dfd5b"
},
{
"path": "skills/gemini-google-search-tool/SKILL.md",
"sha256": "d07a521e379c0d919a7fc2f86e84bc886b6fb2f521d647ed73d335fd0c32849b"
}
],
"dirSha256": "b36cdadd80230dfbc26fcee9151031fdba993386742011c204a985108e2eeef7"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

421
skills/gemini-google-search-tool/SKILL.md Normal file
View File

@@ -0,0 +1,421 @@
---
name: skill-gemini-google-search-tool
description: Query Gemini with Google Search grounding
---
# When to use
- When you need real-time web information beyond the model's training cutoff
- When you need verifiable sources and citations for AI responses
- When you want to reduce hallucinations with Google Search grounding
- When building AI workflows that require up-to-date information
# Gemini Google Search Tool Skill
## Purpose
The gemini-google-search-tool is a Python CLI tool and library that connects Gemini AI models to real-time web content through Google Search grounding. It automatically determines when a search would improve answers, executes appropriate queries, and returns grounded responses with verifiable sources.
## When to Use This Skill
**Use this skill when:**
- You need to query Gemini with real-time web information
- You want automatic citations and source attribution
- You're building AI agents that need current information
- You need to verify AI responses against web sources
- You want to integrate Google Search grounding into workflows
**Do NOT use this skill for:**
- Static knowledge queries that don't need real-time data
- Tasks that don't require source attribution
- Offline-only environments (requires internet and API key)
## CLI Tool: gemini-google-search-tool
A professional CLI-first tool for querying Gemini with Google Search grounding, providing real-time web content with automatic citations.
### Installation
```bash
# Install from source
git clone https://github.com/dnvriend/gemini-google-search-tool.git
cd gemini-google-search-tool
uv tool install .
# Verify installation
gemini-google-search-tool --version
```
### Prerequisites
- Python 3.14 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Google Gemini API key ([get one free](https://aistudio.google.com/app/apikey))
- `GEMINI_API_KEY` environment variable
### Quick Start
```bash
# Set API key
export GEMINI_API_KEY='your-api-key-here'
# Basic query
gemini-google-search-tool query "Who won euro 2024?"
# With inline citations
gemini-google-search-tool query "Latest AI news" --add-citations
# Using pro model
gemini-google-search-tool query "Complex analysis" --pro
```
## Progressive Disclosure
<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>
### query - Query Gemini with Google Search Grounding
Query Gemini models with automatic Google Search grounding for real-time web information.
**Usage:**
```bash
gemini-google-search-tool query "PROMPT" [OPTIONS]
```
**Arguments:**
- `PROMPT`: The query prompt (positional, required unless `--stdin` is used)
- `--stdin` / `-s`: Read prompt from stdin (overrides PROMPT)
- `--add-citations`: Add inline citation links to response text
- `--pro`: Use gemini-2.5-pro model (default: gemini-2.5-flash)
- `--text` / `-t`: Output markdown format instead of JSON
- `-v/-vv/-vvv`: Verbosity levels (INFO/DEBUG/TRACE)
**Examples:**
```bash
# Basic query with JSON output
gemini-google-search-tool query "Who won euro 2024?"
# Query with inline citations
gemini-google-search-tool query "Latest AI developments" --add-citations
# Read from stdin
echo "Climate change updates" | gemini-google-search-tool query --stdin
# Markdown output
gemini-google-search-tool query "Quantum computing news" --text
# Pro model with verbose output
gemini-google-search-tool query "Complex analysis" --pro -vv
# Trace mode (shows HTTP requests)
gemini-google-search-tool query "Test" -vvv
```
**Output (JSON):**
```json
{
"response_text": "AI-generated response with grounding...",
"citations": [
{"index": 1, "uri": "https://...", "title": "Source Title"},
{"index": 2, "uri": "https://...", "title": "Another Source"}
],
"grounding_metadata": {
"web_search_queries": ["query1", "query2"],
"grounding_chunks": [...],
"grounding_supports": [...]
}
}
```
**Output (Markdown with `--text`):**
```markdown
AI-generated response with grounding...
## Citations
1. [Source Title](https://...)
2. [Another Source](https://...)
```
---
### completion - Generate Shell Completion Scripts
Generate shell completion scripts for bash, zsh, or fish.
**Usage:**
```bash
gemini-google-search-tool completion {bash|zsh|fish}
```
**Arguments:**
- `SHELL`: Shell type (bash, zsh, or fish)
**Examples:**
```bash
# Generate and install bash completion
eval "$(gemini-google-search-tool completion bash)"
# Generate and install zsh completion
eval "$(gemini-google-search-tool completion zsh)"
# Install fish completion
mkdir -p ~/.config/fish/completions
gemini-google-search-tool completion fish > ~/.config/fish/completions/gemini-google-search-tool.fish
# Persistent installation (add to ~/.bashrc or ~/.zshrc)
echo 'eval "$(gemini-google-search-tool completion bash)"' >> ~/.bashrc
echo 'eval "$(gemini-google-search-tool completion zsh)"' >> ~/.zshrc
```
**Output:**
Shell-specific completion script to stdout.
</details>
<details>
<summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>
### Google Search Grounding
The tool uses Google Search grounding to connect Gemini to real-time web content:
1. **Automatic Search Decision**: Gemini determines if a search would improve the answer
2. **Query Generation**: Generates appropriate search queries automatically
3. **Result Processing**: Processes search results and synthesizes information
4. **Citation Generation**: Returns grounded responses with verifiable sources
**Benefits:**
- Reduces hallucinations by grounding responses in web content
- Provides up-to-date information beyond training cutoff
- Includes automatic citation links for verification
- Supports multi-query search for comprehensive coverage
### Model Selection
**gemini-2.5-flash (default):**
- Fast response times
- Cost-effective for high-volume queries
- Good for straightforward questions
- Recommended for most use cases
**gemini-2.5-pro (`--pro` flag):**
- More powerful reasoning capabilities
- Better for complex analysis
- Higher quality responses
- More expensive per query
### Verbosity Levels
**No flag (WARNING):**
- Only errors and warnings
- Clean JSON/text output
**`-v` (INFO):**
```
[INFO] Starting query command
[INFO] GeminiClient initialized successfully
[INFO] Querying with model 'gemini-2.5-flash' and Google Search grounding
[INFO] Query completed successfully
```
**`-vv` (DEBUG):**
```
[DEBUG] Validated prompt: Who won euro 2024?...
[DEBUG] Initializing GeminiClient
[DEBUG] Calling Gemini API: model=gemini-2.5-flash
[DEBUG] Extracted 7 citations
[DEBUG] Web search queries: ['who won euro 2024', 'Euro 2024 winner']
```
**`-vvv` (TRACE):**
```
[DEBUG] connect_tcp.started host='generativelanguage.googleapis.com' port=443
[DEBUG] start_tls.started ssl_context=<ssl.SSLContext...>
[DEBUG] send_request_headers.started request=<Request [b'POST']>
```
### Library Usage
The tool can also be used as a Python library:
```python
from gemini_google_search_tool import (
GeminiClient,
query_with_grounding,
add_inline_citations,
)
# Initialize client
client = GeminiClient() # Reads GEMINI_API_KEY from environment
# Query with grounding
response = query_with_grounding(
client=client,
prompt="Who won euro 2024?",
model="gemini-2.5-flash",
)
# Access response
print(response.response_text)
print(f"Citations: {len(response.citations)}")
# Add inline citations
if response.grounding_segments:
text_with_citations = add_inline_citations(
response.response_text,
response.grounding_segments,
response.citations,
)
print(text_with_citations)
```
### Pipeline Integration
The tool follows CLI-first design principles for pipeline integration:
**JSON to stdout, logs to stderr:**
```bash
# Parse JSON output
gemini-google-search-tool query "test" | jq '.response_text'
# Filter citations
gemini-google-search-tool query "test" | jq '.citations[]'
# Check exit code
gemini-google-search-tool query "test" && echo "Success"
```
**Stdin support:**
```bash
# From file
cat question.txt | gemini-google-search-tool query --stdin
# From command output
echo "Who won euro 2024?" | gemini-google-search-tool query --stdin
```
</details>
<details>
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>
### Common Issues
**Issue: Missing API Key**
```bash
Error: GEMINI_API_KEY environment variable is required.
Set it with: export GEMINI_API_KEY='your-api-key'
```
**Solution:**
1. Get an API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Set environment variable: `export GEMINI_API_KEY='your-key'`
3. Or add to shell profile: `echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc`
---
**Issue: Empty or Invalid Response**
```bash
Error: Query failed: Invalid response format
```
**Solution:**
1. Check API key is valid
2. Verify internet connection
3. Try with verbose mode: `-vv` to see detailed error
4. Check Gemini API status page
---
**Issue: Rate Limiting**
```bash
Error: Query failed: Rate limit exceeded
```
**Solution:**
1. Wait and retry
2. Check API quota in Google AI Studio
3. Consider upgrading API tier for higher limits
---
**Issue: Module Import Error (Library Usage)**
```python
ImportError: No module named 'gemini_google_search_tool'
```
**Solution:**
1. Install package: `uv tool install .`
2. Or use in development: `uv sync` then `uv run python script.py`
3. Verify installation: `python -c "import gemini_google_search_tool"`
### Getting Help
```bash
# General help
gemini-google-search-tool --help
# Command-specific help
gemini-google-search-tool query --help
gemini-google-search-tool completion --help
# Version info
gemini-google-search-tool --version
```
### Debug Mode
Use `-vv` or `-vvv` for detailed debugging:
```bash
# Debug API calls and response processing
gemini-google-search-tool query "test" -vv
# Trace HTTP requests (shows full request/response)
gemini-google-search-tool query "test" -vvv
```
</details>
## Exit Codes
- `0`: Success - query completed successfully
- `1`: Error - client error, invalid arguments, or query failure
## Output Formats
**JSON (default):**
- Structured output with response_text and citations
- Machine-parseable for pipeline integration
- Always includes citations array
- Optional grounding_metadata with `-vv` or `-vvv`
**Markdown (`--text`):**
- Human-readable format
- Response text followed by citations section
- Good for direct reading or documentation
**Verbosity (stderr):**
- Logs and verbose output go to stderr
- Keeps stdout clean for JSON parsing
- Use `-v/-vv/-vvv` for progressively more detail
## Best Practices
1. **Use Flash Model by Default**: The gemini-2.5-flash model is fast and cost-effective for most queries
2. **Add Citations for Verification**: Use `--add-citations` when you need inline source links
3. **Pipeline Integration**: Pipe JSON output through `jq` for structured data processing
4. **Verbosity for Debugging**: Use `-vv` when troubleshooting, `-vvv` for HTTP-level details
5. **Environment Variables**: Store API key securely in shell profile, not in scripts
6. **Error Handling**: Always check exit codes when using in scripts or automation
7. **Model Selection**: Use `--pro` for complex analysis requiring deeper reasoning
## Resources
- **GitHub Repository**: https://github.com/dnvriend/gemini-google-search-tool
- **Google Search Grounding Docs**: https://ai.google.dev/gemini-api/docs/grounding
- **Gemini API Documentation**: https://ai.google.dev/gemini-api/docs
- **Get API Key**: https://aistudio.google.com/app/apikey
- **Python Package**: Installable via `uv tool install`
- **Developer Guide**: See CLAUDE.md in repository