### GroundCite Development Setup

Source: https://github.com/cennest/ground-cite/blob/main/README.md

Steps to set up the GroundCite development environment. This includes cloning the repository, creating a virtual environment, and installing dependencies in development mode.

```bash
# Clone the repository
git clone https://github.com/cennest/ground-cite.git
cd ground-cite/GroundCite

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"
```

--------------------------------

### Install GroundCite from Source

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/README.md

Clone the repository and install the package in editable mode.

```bash
git clone https://github.com/cennest/ground-cite.git
cd ground-cite/GroundCite
pip install -e .
```

--------------------------------

### Install development dependencies

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Installs the project in editable mode with development dependencies.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Install and Verify GroundCite CLI

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Use pip to install the package and verify the installation with the help command.

```bash
# Install GroundCite
pip install gemini-groundcite

# Verify installation
gemini-groundcite --help
```

--------------------------------

### Start REST API Server

Source: https://github.com/cennest/ground-cite/blob/main/README.md

Command to launch the FastAPI-based web service.

```bash
python -m gemini_groundcite.main
```

--------------------------------

### Install GroundCite

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/FAQ.md

Install the library via pip.

```bash
pip install gemini-groundcite
```

--------------------------------

### Install GroundCite

Source: https://context7.com/cennest/ground-cite/llms.txt

Commands to install the library from source or via pip.

```bash
# Install from source
git clone https://github.com/cennest/ground-cite.git
cd ground-cite/GroundCite
pip install -e .

# Or using pip (when published)
pip install gemini-groundcite
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/README.md

Clone the GroundCite repository, navigate to the directory, create a virtual environment, activate it, and install the project in development mode with dev dependencies.

```bash
git clone https://github.com/cennest/ground-cite.git
cd ground-cite/GroundCite
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

--------------------------------

### Run the REST API

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/FAQ.md

Start the local development server for the GroundCite REST API.

```bash
uvicorn gemini_groundcite.main:app --reload
```

--------------------------------

### REST API: Start Server

Source: https://context7.com/cennest/ground-cite/llms.txt

Start the GroundCite API server using Python's built-in module or uvicorn. Ensure the correct host and port are specified.

```bash
# Start the API server
python -m gemini_groundcite.main
# Or with uvicorn
uvicorn gemini_groundcite.main:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Google-Style Docstring Example

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Standard format for documenting asynchronous methods with arguments, return types, and exceptions.

```python
async def analyze_query(
    self, 
    query: str,
    max_retries: int = 3
) -> Optional[Dict[str, Any]]:
    """
    Analyze a query using the configured AI pipeline.
    
    This method orchestrates the complete analysis workflow including
    search, validation, and parsing stages based on configuration.
    
    Args:
        query (str): The query to analyze
        max_retries (int): Maximum number of retry attempts
    
    Returns:
        Optional[Dict[str, Any]]: Analysis results containing search results,
            validated content, and parsed data if successful
    
    Raises:
        AIAgentError: If the analysis pipeline fails
        ConfigurationError: If configuration is invalid
    
    Example:
        >>> agent = AIAgent(settings)
        >>> result = await agent.analyze_query("What is AI?")
        >>> print(result['final_content'])
    """
```

--------------------------------

### Missing API Key Error Example

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

An example of an error response when a required API key is missing for a provider like Gemini.

```json
{
  "success": false,
  "error": "Gemini API key is required",
  "execution_time": 0.001,
  "correlation_id": "abc123"
}
```

--------------------------------

### Validate inputs with minimal configuration

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Test system behavior using a minimal configuration setup to isolate potential issues.

```python
# Test with minimal configuration
settings = AppSettings()
settings.ANALYSIS_CONFIG.query = "test"
settings.AI_CONFIG.gemini_ai_key_primary = "your_key"

is_valid, errors = settings.validate_all_configurations()
print(f"Valid: {is_valid}, Errors: {errors}")
```

--------------------------------

### Interact with GroundCite REST API

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/README.md

Start the server and send POST requests to the analysis endpoint.

```bash
# Start the API server
python -m gemini_groundcite.main

# Make analysis requests
curl -X POST "http://localhost:8000/api/v1/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Latest AI developments",
    "config": {"validate": true, "parse": true},
    "search_model_name": "gemini-2.5-flash",
    "api_keys": {"gemini": {"primary": "your_key"}}
  }'
```

--------------------------------

### Validate and Get Configuration Summary

Source: https://context7.com/cennest/ground-cite/llms.txt

Validate all current configurations using `validate_all_configurations()`. Retrieve a summary of the configuration, excluding sensitive data like API keys, using `get_configuration_summary()`.

```python
# Validate all configurations
is_valid, errors = settings.validate_all_configurations()
if not is_valid:
    print(f"Configuration errors: {errors}")
else:
    print("Configuration is valid")

# Get configuration summary (excludes sensitive data like API keys)
summary = settings.get_configuration_summary()
print(f"Has Gemini Key: {summary['ai_config']['has_gemini_key']}")
print(f"Parsing Provider: {summary['ai_config']['parsing_provider']}")
print(f"Validation Enabled: {summary['analysis_config']['validation_enabled']}")
```

--------------------------------

### GET /api/v1/configurations

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Retrieves all saved analysis configurations.

```APIDOC
## GET /api/v1/configurations

### Description
Retrieves all saved analysis configurations.

### Method
GET

### Endpoint
/api/v1/configurations

### Response
#### Success Response (200)
- **configurations** (array) - List of saved configuration objects
- **total** (integer) - Total count of configurations
```

--------------------------------

### Execute Query Analysis via cURL

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Example request for performing a query analysis with validation and parsing enabled using the Gemini provider.

```bash
curl -X POST "http://localhost:8000/api/v1/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest developments in quantum computing?",
    "config": {
      "validate": true,
      "parse": true,
      "schema": "{\"title\":{\"type\":\"string\"},\"summary\":{\"type\":\"string\"},\"key_developments\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}"
    },
    "search_model_name": "gemini-2.5-flash",
    "validate_model_name": "gemini-2.5-flash",
    "parse_model_name": "gemini-2.5-flash",
    "parsing_provider": "gemini",
    "api_keys": {
      "gemini": {
        "primary": "your_gemini_api_key"
      }
    }
  }'
```

--------------------------------

### GET /

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Provides a basic health check and general API information.

```APIDOC
## GET /

### Description
Basic health check and API information.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
Returns basic API information and health status.
```

--------------------------------

### Retrieve Configurations Response

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

JSON response format for the GET /api/v1/configurations endpoint, listing all saved analysis configurations.

```json
{
  "configurations": [
    {
      "id": "uuid",
      "name": "string",
      "description": "string",
      "config": {},
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    }
  ],
  "total": 1
}
```

--------------------------------

### Set up virtual environment

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Commands to create and activate a Python virtual environment for development.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### CLI: Using Different Models and Providers

Source: https://context7.com/cennest/ground-cite/llms.txt

Specify different AI models for search, validation, and parsing stages, and select the AI provider. Requires API keys for each provider used.

```bash
# Using different models for different stages
gemini-groundcite analyze \
  -q "Blockchain technology overview" \
  --search_model gemini-1.5-pro \
  --validate_model gemini-2.5-flash \
  --parse_model gpt-4 \
  --provider openai \
  --validate \
  --parse \
  --gemini-key your_gemini_key \
  --openai-key your_openai_key
```

--------------------------------

### Invalid Schema Error Example

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

An example of an error response when an invalid JSON schema is provided in the request.

```json
{
  "success": false,
  "error": "Invalid JSON schema provided",
  "execution_time": 0.1,
  "correlation_id": "def456"
}
```

--------------------------------

### CLI: Simple Query Analysis

Source: https://context7.com/cennest/ground-cite/llms.txt

Perform a basic query analysis using the CLI. Requires a query and your Gemini API key. Use `--gemini-key` for authentication.

```bash
# Simple query analysis
gemini-groundcite analyze \
  -q "What are the benefits of renewable energy?" \
  --gemini-key your_gemini_api_key
```

--------------------------------

### API Key Management: Configuration Files

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Shows how to load API keys from a JSON configuration file, another secure method to avoid hardcoding.

```python
# ✅ Good - Use configuration files
import json
with open("config.json") as f:
    config = json.load(f)
    settings.AI_CONFIG.gemini_ai_key_primary = config["gemini_key"]
```

--------------------------------

### Initialize Python Library

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Configure application settings and initialize the AIAgent for programmatic use.

```python
import asyncio
from gemini_groundcite.config.settings import AppSettings
from gemini_groundcite.core.agents import AIAgent

# Configure settings
settings = AppSettings()
settings.AI_CONFIG.gemini_ai_key_primary = "your_key"
settings.ANALYSIS_CONFIG.validate = True
settings.ANALYSIS_CONFIG.parse = True

# Initialize agent
agent = AIAgent(settings=settings)
```

--------------------------------

### GET /api/v1/health

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Performs a comprehensive health check of the GroundCite service.

```APIDOC
## GET /api/v1/health

### Description
Comprehensive health check endpoint.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- **status** (string) - The current status of the service (e.g., 'healthy').
- **timestamp** (string) - The timestamp of the health check.
- **version** (string) - The current version of the GroundCite service.
- **groundcite_ready** (boolean) - Indicates if GroundCite is ready to process requests.

#### Response Example
```json
{
  "status": "healthy",
  "timestamp": "2025-01-01T00:00:00",
  "version": "1.1.0",
  "groundcite_ready": true
}
```
```

--------------------------------

### API Key Management: Environment Variables

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Demonstrates the recommended practice of using environment variables to manage sensitive API keys, avoiding hardcoding.

```python
# Don't hardcode API keys
# ❌ Bad
settings.AI_CONFIG.gemini_ai_key_primary = "actual_api_key_here"

# ✅ Good - Use environment variables
import os
settings.AI_CONFIG.gemini_ai_key_primary = os.getenv("GEMINI_AI_KEY_PRIMARY")
```

--------------------------------

### GET /api/v1/configurations/{config_id}

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Retrieves a specific analysis configuration by its ID.

```APIDOC
## GET /api/v1/configurations/{config_id}

### Description
Retrieves a specific configuration by ID.

### Method
GET

### Endpoint
/api/v1/configurations/{config_id}

### Parameters
#### Path Parameters
- **config_id** (string) - Required - The ID of the configuration to retrieve.
```

--------------------------------

### Error Handling

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Details on the error response format, common error codes, and examples.

```APIDOC
## Error Handling

### Error Response Format

```json
{
  "success": false,
  "error": "Error description",
  "execution_time": 1.23,
  "correlation_id": "uuid"
}
```

### Common Error Codes

| HTTP Code | Error Type | Description |
|-----------|------------|-------------|
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Missing or invalid API keys |
| 404 | Not Found | Configuration not found |
| 422 | Validation Error | Request validation failed |
| 500 | Internal Error | Server processing error |
| 503 | Service Unavailable | AI provider unavailable |

### Error Examples

#### Missing API Key
```json
{
  "success": false,
  "error": "Gemini API key is required",
  "execution_time": 0.001,
  "correlation_id": "abc123"
}
```

#### Invalid Schema
```json
{
  "success": false,
  "error": "Invalid JSON schema provided",
  "execution_time": 0.1,
  "correlation_id": "def456"
}
```
```

--------------------------------

### CLI: Configuration Management and Version

Source: https://context7.com/cennest/ground-cite/llms.txt

Manage GroundCite configuration using `gemini-groundcite config`. Use `--show` to display current settings and `--validate` to check their validity. Check the version with `gemini-groundcite version`.

```bash
# Configuration management
gemini-groundcite config --show      # Show current configuration
gemini-groundcite config --validate  # Validate current configuration

# Version information
gemini-groundcite version
```

--------------------------------

### Interfaces Structure

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/ARCHITECTURE.md

File structure for entry points and interface implementations.

```text
gemini_groundcite/
├── cli.py          # Command-line interface
├── main.py         # FastAPI web service
└── __main__.py     # Python module entry point
```

--------------------------------

### Run a basic query

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/FAQ.md

Execute a research query using the Gemini API key.

```bash
gemini-groundcite analyze -q "What are the benefits of renewable energy?" --gemini-key your_gemini_key
```

--------------------------------

### Schema Design: Avoid Complexity

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Highlights an example of an overly complex and deeply nested JSON schema, which should be avoided for maintainability.

```json
# ❌ Avoid overly complex schemas
bad_schema = {
    "type": "object",
    "properties": {
        "deeply": {
            "type": "object",
            "properties": {
                "nested": {
                    "type": "object",
                    "properties": {
                        "structure": {"type": "string"}
                    }
                }
            }
        }
    }
}
```

--------------------------------

### Clone the repository

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Initial step to obtain a local copy of the project from a GitHub fork.

```bash
# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/ground-cite.git
cd ground-cite/GroundCite
```

--------------------------------

### Configure CLI Providers and Models

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Customize the AI provider and specific models used for different stages of the analysis pipeline.

```bash
# Use OpenAI for parsing
gemini-groundcite analyze \
  -q "AI ethics considerations" \
  --provider openai \
  --parse \
  --parse_model gpt-4 \
  --gemini-key your_gemeni_key \
  --openai-key your_openai_key 


# Use different models for different stages
gemini-groundcite analyze \
  -q "Blockchain technology overview" \
  --search_model gemini-1.5-pro \
  --validate_model gemini-2.5-flash \
  --parse_model gpt-4 \
  --provider openai \
  --validate \
  --parse
  --gemini-key your_gemeni_key \
  --openai-key your_openai_key
```

--------------------------------

### Execute Fact-Checking Analysis

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Verifies claims against authoritative sources using a structured validation schema. The system instruction guides the AI to provide confidence scores and evidence.

```python
async def fact_check_analysis(claim):
    """Fact-check claims with validation focus"""
    settings = AppSettings()
    
    settings.ANALYSIS_CONFIG.query = f"Fact-check and verify: {claim}"
    settings.ANALYSIS_CONFIG.system_instruction = """
    Carefully verify the accuracy of the given claim.
    Look for authoritative sources and evidence.
    Be explicit about confidence levels and source credibility.
    """
    settings.ANALYSIS_CONFIG.validate = True
    settings.ANALYSIS_CONFIG.parse = True
    settings.ANALYSIS_CONFIG.parse_schema = '''
    {
        "type": "object",
        "properties": {
            "claim": {"type": "string"},
            "verdict": {
                "type": "string",
                "enum": ["True", "False", "Partially True", "Misleading", "Unverifiable"]
            },
            "confidence_score": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
            },
            "supporting_evidence": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "evidence": {"type": "string"},
                        "source": {"type": "string"},
                        "credibility_rating": {"type": "string"}
                    }
                }
            },
            "contradicting_evidence": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "evidence": {"type": "string"},
                        "source": {"type": "string"}
                    }
                }
            },
            "context": {"type": "string"},
            "caveats": {"type": "string"}
        }
    }
    '''
    
    # Include authoritative news and fact-checking sites
    settings.ANALYSIS_CONFIG.included_sites = "https://www.snopes.com,https://www.factcheck.org,https://www.politifact.com,https://www.reuters.com,https://www.ap.org"
    
    settings.AI_CONFIG.gemini_ai_key_primary = "your_key"
    
    agent = AIAgent(settings=settings)
    return await agent.analyze_query()

# Example usage
result = asyncio.run(fact_check_analysis(
    "Vaccines cause autism in children"
))
```

--------------------------------

### Reuse Configurations in Python

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Demonstrates saving a configuration object to the API and referencing it by ID in subsequent requests.

```python
import requests

# Save frequently used configurations
config_response = requests.post('/api/v1/configurations', json={
    "name": "Standard Analysis",
    "config": {"validate": True, "parse": True},
    # ... other settings
})

config_id = config_response.json()['id']

# Reuse configuration
analysis_response = requests.post('/api/v1/analyze', json={
    "query": "New query",
    "configuration_id": config_id  # Future feature
})
```

--------------------------------

### Dependency Injection Structure

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/ARCHITECTURE.md

File structure for the IoC container module.

```text
di/
├── __init__.py
└── core_di.py       # CoreDi - IoC container
```

--------------------------------

### Execute CLI Analysis

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/README.md

Run queries through the command line interface with optional validation, parsing, and provider configuration.

```bash
# Simple query analysis
gemini-groundcite analyze -q "What are the latest developments in AI?" --gemini-key your_gemini_key

# With validation and parsing
gemini-groundcite analyze -q "Company X financials" --validate --parse --gemini-key your_gemini_key

# Using OpenAI provider
gemini-groundcite analyze -q "Market trends" --provider openai --openai-key your_key --gemini-key your_gemini_key
```

--------------------------------

### Enable validation

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/FAQ.md

Run a query with citation and relevance validation enabled.

```bash
gemini-groundcite analyze -q "query" --validate --gemini-key your_gemini_key
```

--------------------------------

### Configure AI Model Names and Parameters

Source: https://context7.com/cennest/ground-cite/llms.txt

Set model names for different pipeline stages (search, validate, parse) and configure provider-specific parameters like temperature and token limits. Ensure 'parsing_provider' is set to 'gemini' or 'openai'.

```python
settings.AI_CONFIG.search_model_name = "gemini-2.5-flash"
settings.AI_CONFIG.validate_model_name = "gemini-2.5-flash"
settings.AI_CONFIG.parse_model_name = "gemini-1.5-pro"
settings.AI_CONFIG.parsing_provider = "gemini"  # or "openai"

settings.AI_CONFIG.search_gemini_params = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
    "max_output_tokens": 2048
}

settings.AI_CONFIG.parsing_gemini_params = {
    "temperature": 0.1,  # Lower for more consistent parsing
    "max_output_tokens": 4096
}

settings.AI_CONFIG.parsing_openai_params = {
    "temperature": 0.1,
    "max_tokens": 4096,
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
}
```

--------------------------------

### Monitoring and Logging: Token Usage

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Sets up a callback function to log token usage and execution time metrics from analysis results, aiding in performance monitoring.

```python
import logging

def setup_monitoring(agent):
    """Set up monitoring for analysis operations"""
    
    # Track token usage
    def log_token_usage(result):
        if result and 'execution_metrics' in result:
            metrics = result['execution_metrics']
            token_usage = metrics.get('token_usage', {})
            
            total_tokens = 0
            for operation, usage_list in token_usage.items():
                for usage in usage_list:
                    total_tokens += usage.get('total_tokens', 0)
            
            logging.info(f"Total tokens used: {total_tokens}")
            logging.info(f"Execution time: {metrics.get('execution_time_seconds', 0):.2f}s")
    
    return log_token_usage

# Usage
monitor = setup_monitoring(agent)
result = await agent.analyze_query("test query")
monitor(result)
```

--------------------------------

### Create a feature branch

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Commands to initialize a new branch for specific features or bug fixes.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
```

--------------------------------

### Advanced Analysis with Custom Configuration

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Configure detailed analysis settings, including query, system instructions, validation, parsing schemas, AI models, and site filtering. Initialize and run the AI agent with these custom settings.

```python
async def advanced_analysis():
    # Detailed configuration
    settings = AppSettings()
    
    # Analysis configuration
    settings.ANALYSIS_CONFIG.query = "Impact of AI on healthcare"
    settings.ANALYSIS_CONFIG.system_instruction = "Focus on evidence-based analysis"
    settings.ANALYSIS_CONFIG.validate = True
    settings.ANALYSIS_CONFIG.parse = True
    settings.ANALYSIS_CONFIG.parse_schema = '''
    {
        "type": "object",
        "properties": {
            "executive_summary": {"type": "string"},
            "key_impacts": {
                "type": "array",
                "items": {"type": "string"}
            },
            "benefits": {
                "type": "array",
                "items": {"type": "string"}
            },
            "challenges": {
                "type": "array",
                "items": {"type": "string"}
            },
            "future_outlook": {"type": "string"},
            "confidence_score": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
            }
        },
        "required": ["executive_summary", "key_impacts"]
    }
    '''
    
    # AI configuration
    settings.AI_CONFIG.gemini_ai_key_primary = "your_key"
    settings.AI_CONFIG.search_model_name = "gemini-1.5-pro"
    settings.AI_CONFIG.validate_model_name = "gemini-2.5-flash"
    settings.AI_CONFIG.parse_model_name = "gemini-1.5-pro"
    
    # Site filtering
    settings.ANALYSIS_CONFIG.included_sites = "https://www.pubmed.ncbi.nlm.nih.gov,https://www.nejm.org,https://www.nature.com"
    
    # Initialize and run
    agent = AIAgent(settings=settings)
    result = await agent.analyze_query()
    
    return result

# Execute analysis
result = asyncio.run(advanced_analysis())
print(result['final_content'])
```

--------------------------------

### Configure AI Provider Parameters

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Sets specific hyperparameters for Gemini and OpenAI providers within the AppSettings configuration.

```python
# Gemini-specific parameters
settings.AI_CONFIG.search_gemini_params = {
    "temperature": 0.7,          # Creativity level
    "top_p": 0.9,               # Nucleus sampling
    "top_k": 40,                # Top-k sampling
    "max_output_tokens": 2048,   # Response length
}

# OpenAI-specific parameters
settings.AI_CONFIG.parsing_openai_params = {
    "temperature": 0.1,          # Low for structured parsing
    "max_tokens": 4096,          # Maximum tokens
    "top_p": 1.0,               # Nucleus sampling
    "frequency_penalty": 0.0,    # Frequency penalty
    "presence_penalty": 0.0,     # Presence penalty
}
```

--------------------------------

### CLI: Full Pipeline Analysis with Custom Schema

Source: https://context7.com/cennest/ground-cite/llms.txt

Execute a full analysis pipeline including validation and parsing with a custom JSON schema. Use `--validate`, `--parse`, and `--schema` flags. Verbose output is enabled with `--verbose`.

```bash
# Full pipeline with validation, parsing, and custom schema
gemini-groundcite analyze \
  -q "Market analysis for electric vehicles" \
  --validate \
  --parse \
  --schema '{
    "market_size": {"type": "string"},
    "key_players": {"type": "array", "items": {"type": "string"}},
    "growth_rate": {"type": "string"},
    "challenges": {"type": "array", "items": {"type": "string"}}
  }' \
  --gemini-key your_gemini_api_key \
  --verbose
```

--------------------------------

### Perform Technical Documentation Analysis

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Uses an AIAgent to generate structured technical overviews for a given technology. Requires an AppSettings object with a defined JSON schema for parsing.

```python
async def technical_analysis(technology):
    """Analyze technical topics with implementation details"""
    settings = AppSettings()
    
    settings.ANALYSIS_CONFIG.query = f"Technical overview and implementation of {technology}"
    settings.ANALYSIS_CONFIG.validate = True
    settings.ANALYSIS_CONFIG.parse = True
    settings.ANALYSIS_CONFIG.parse_schema = '''
    {
        "type": "object",
        "properties": {
            "technology_overview": {"type": "string"},
            "key_concepts": {
                "type": "array",
                "items": {"type": "string"}
            },
            "implementation_approaches": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "approach": {"type": "string"},
                        "pros": {"type": "array", "items": {"type": "string"}},
                        "cons": {"type": "array", "items": {"type": "string"}}
                    }
                }
            },
            "best_practices": {
                "type": "array",
                "items": {"type": "string"}
            },
            "common_pitfalls": {
                "type": "array",
                "items": {"type": "string"}
            },
            "tools_and_frameworks": {
                "type": "array",
                "items": {"type": "string"}
            }
        }
    }
    '''
    
    # Include technical documentation sources
    settings.ANALYSIS_CONFIG.included_sites = "https://www.github.com,https://www.stackoverflow.com,https://www.medium.com,https://www.dev.to"
    
    settings.AI_CONFIG.gemini_ai_key_primary = "your_key"
    
    agent = AIAgent(settings=settings)
    return await agent.analyze_query()

# Example usage
result = asyncio.run(technical_analysis("microservices architecture"))
```

--------------------------------

### Configure GroundCite from Environment Variables

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Loads application settings by reading values from environment variables. Supports AI keys, analysis validation, parsing flags, and site inclusion/exclusion.

```python
import os

def configure_from_environment():
    """Configure GroundCite from environment variables"""
    settings = AppSettings()
    
    # AI keys from environment
    settings.AI_CONFIG.gemini_ai_key_primary = os.getenv("GEMINI_AI_KEY_PRIMARY")
    settings.AI_CONFIG.open_ai_key = os.getenv("OPENAI_API_KEY")
    
    # Analysis settings from environment
    settings.ANALYSIS_CONFIG.validate = os.getenv("ANALYSIS_VALIDATE", "false").lower() == "true"
    settings.ANALYSIS_CONFIG.parse = os.getenv("ANALYSIS_PARSE", "false").lower() == "true"
    
    # Site filtering from environment
    settings.ANALYSIS_CONFIG.included_sites = os.getenv("ANALYSIS_INCLUDED_SITES", "")
    settings.ANALYSIS_CONFIG.excluded_sites = os.getenv("ANALYSIS_EXCLUDED_SITES", "")
    
    return settings
```

--------------------------------

### Configure Analysis Settings and Site Filtering

Source: https://context7.com/cennest/ground-cite/llms.txt

Define analysis queries, system instructions, and enable/disable validation and parsing. Specify included and excluded websites for filtering search results. Use 'True' or 'False' for boolean settings.

```python
# Analysis Configuration
settings.ANALYSIS_CONFIG.query = "Impact of AI on healthcare"
settings.ANALYSIS_CONFIG.system_instruction = "Focus on evidence-based analysis from peer-reviewed sources"
settings.ANALYSIS_CONFIG.validate = True
settings.ANALYSIS_CONFIG.parse = True
settings.ANALYSIS_CONFIG.parse_schema = '{"summary": {"type": "string"}, "findings": {"type": "array"}}'

# Site filtering
settings.ANALYSIS_CONFIG.included_sites = "pubmed.ncbi.nlm.nih.gov,nejm.org,nature.com"
settings.ANALYSIS_CONFIG.excluded_sites = "spam.com,unreliable.net"
```

--------------------------------

### Configuration Layer Structure

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/ARCHITECTURE.md

File structure for the configuration management module.

```text
config/
├── __init__.py
├── settings.py      # AppSettings - Central configuration
└── logger.py        # AppLogger - Logging infrastructure
```

--------------------------------

### Perform Query Analysis via CLI

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Execute basic queries or complex pipelines with validation and schema-based parsing.

```bash
# Simple query analysis
gemini-groundcite analyze -q "What are the benefits of renewable energy?" --gemini-key your_gemeni_key

# With validation and structured parsing
gemini-groundcite analyze \
  -q "Latest developments in quantum computing" \
  --validate \
  --parse \
  --schema '{"summary": {"type": "string"}, "developments": {"type": "array"}}' \
  --gemini-key your_gemeni_key
```

```bash
gemini-groundcite analyze -q "How does machine learning work?" --gemini-key your_gemeni_key
```

```bash
gemini-groundcite analyze \
  -q "Climate change impact on agriculture" \
  --validate \
  --gemini-key your_gemeni_key \
  --verbose
```

```bash
gemini-groundcite analyze \
  -q "Market analysis for electric vehicles" \
  --validate \
  --parse \
  --schema '{
    "market_size": {"type": "string"},
    "key_players": {"type": "array", "items": {"type": "string"}},
    "growth_rate": {"type": "string"},
    "challenges": {"type": "array", "items": {"type": "string"}}
  }' \
  --gemini-key your_gemeni_key \
  --verbose
```

--------------------------------

### Configure AppSettings

Source: https://context7.com/cennest/ground-cite/llms.txt

The AppSettings class manages AI and analysis configurations. It is typically initialized with environment variables for API keys.

```python
from gemini_groundcite.config.settings import AppSettings, AIConfig, AnalysisConfig
import os

# Initialize settings
settings = AppSettings()

# AI Configuration - API keys and model settings
settings.AI_CONFIG.gemini_ai_key_primary = os.getenv("GEMINI_API_KEY")
settings.AI_CONFIG.gemini_ai_key_secondary = os.getenv("GEMINI_API_KEY_BACKUP")  # Fallback key
settings.AI_CONFIG.open_ai_key = os.getenv("OPENAI_API_KEY")
```

--------------------------------

### Validate AppSettings configurations

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Use this to identify and resolve configuration errors by checking validation results and applying common fixes.

```python
settings = AppSettings()
is_valid, errors = settings.validate_all_configurations()

if not is_valid:
    print("Configuration errors:")
    for error in errors:
        print(f"  - {error}")
    
    # Common fixes
    if "query" in str(errors):
        settings.ANALYSIS_CONFIG.query = "test query"
    
    if "gemini_key" in str(errors):
        settings.AI_CONFIG.gemini_ai_key_primary = os.getenv("GEMINI_AI_KEY_PRIMARY")
```

--------------------------------

### CLI: Site Filtering - Include Academic Sources

Source: https://context7.com/cennest/ground-cite/llms.txt

Filter search results to include only specified academic domains. Use the `--include-sites` flag with a comma-separated list of domains.

```bash
# Site filtering - include only academic sources
gemini-groundcite analyze \
  -q "Quantum computing research" \
  --include-sites "arxiv.org,nature.com,science.org" \
  --parse \
  --gemini-key your_gemini_key
```

--------------------------------

### Integrate GroundCite in Python

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/README.md

Configure application settings and initialize the AIAgent to perform analysis programmatically.

```python
from gemini_groundcite.config.settings import AppSettings
from gemini_groundcite.core.agents import AIAgent

# Configure settings
settings = AppSettings()
settings.ANALYSIS_CONFIG.query = "What are quantum computing breakthroughs?"
settings.ANALYSIS_CONFIG.validate = True
settings.ANALYSIS_CONFIG.parse = True
settings.AI_CONFIG.gemini_ai_key_primary = "your_gemini_key"

# Initialize and run analysis
agent = AIAgent(settings=settings)
results = await agent.analyze_query()

print(f"Analysis completed: {results['completed']}")
print(f"Results: {results['final_content']}")
```

--------------------------------

### Manage Analysis Configurations

Source: https://context7.com/cennest/ground-cite/llms.txt

Endpoints for CRUD operations on reusable analysis configurations.

```bash
# Save a new configuration
curl -X POST "http://localhost:8000/api/v1/configurations" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Analysis Config",
    "description": "Configuration for academic research analysis",
    "config": {
      "validate": true,
      "parse": true,
      "schema": "{\"findings\":{\"type\":\"array\"},\"methodology\":{\"type\":\"string\"},\"conclusion\":{\"type\":\"string\"}}"
    },
    "parsing_provider": "gemini",
    "search_model_name": "gemini-1.5-pro",
    "validate_model_name": "gemini-2.5-flash",
    "parse_model_name": "gemini-1.5-pro",
    "api_keys": {
      "gemini": {"primary": "your_key"}
    }
  }'

# Get all saved configurations
curl -X GET "http://localhost:8000/api/v1/configurations"

# Get a specific configuration by ID
curl -X GET "http://localhost:8000/api/v1/configurations/{config_id}"

# Update a configuration
curl -X PUT "http://localhost:8000/api/v1/configurations/{config_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Research Config",
    "description": "Updated configuration",
    "config": {"validate": true, "parse": true},
    "parsing_provider": "gemini",
    "search_model_name": "gemini-2.5-flash",
    "api_keys": {"gemini": {"primary": "your_key"}}
  }'

# Delete a configuration
curl -X DELETE "http://localhost:8000/api/v1/configurations/{config_id}"
```

--------------------------------

### Define New AI Provider Client

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Template for implementing a new AI provider client class.

```python
# gemini_groundcite/core/agents/clients/new_provider_client.py
class NewProviderClient:
    async def generate_content(
        self, 
        prompt: str, 
        model: str, 
        **kwargs
    ) -> GenerationResponse:
        """Implement the common interface"""
```

--------------------------------

### REST API: Basic Analysis Request

Source: https://context7.com/cennest/ground-cite/llms.txt

Perform a basic analysis request via POST to `/api/v1/analyze`. Include query, configuration options, model names, parsing provider, and API keys in the JSON payload.

```bash
# Basic analysis request
curl -X POST "http://localhost:8000/api/v1/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest developments in quantum computing?",
    "config": {
      "validate": true,
      "parse": true,
      "schema": "{\"title\":{\"type\":\"string\"},\"summary\":{\"type\":\"string\"},\"key_developments\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}"
    },
    "search_model_name": "gemini-2.5-flash",
    "validate_model_name": "gemini-2.5-flash",
    "parse_model_name": "gemini-2.5-flash",
    "parsing_provider": "gemini",
    "api_keys": {
      "gemini": {
        "primary": "your_gemini_api_key"
      }
    }
  }'
```

--------------------------------

### Implement GroundCite JavaScript Client

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Provides a client class for browser or Node.js environments using the Fetch API.

```javascript
class GroundCiteClient {
  constructor(baseUrl = 'http://localhost:8000', geminiKey = null) {
    this.baseUrl = baseUrl;
    this.geminiKey = geminiKey;
  }
  
  async analyze(query, options = {}) {
    const {
      validate = false,
      parse = false,
      schema = '{}',
      provider = 'gemini'
    } = options;
    
    const payload = {
      query,
      config: { validate, parse, schema },
      search_model_name: 'gemini-2.5-flash',
      parsing_provider: provider,
      api_keys: {
        gemini: { primary: this.geminiKey }
      }
    };
    
    if (validate) payload.validate_model_name = 'gemini-2.5-flash';
    if (parse) payload.parse_model_name = 'gemini-2.5-flash';
    
    const response = await fetch(`${this.baseUrl}/api/v1/analyze`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    
    const result = await response.json();
    if (!result.success) {
      throw new Error(result.error);
    }
    
    return result.data;
  }
}

// Usage
const client = new GroundCiteClient('http://localhost:8000', 'your_key');
const result = await client.analyze('What is quantum computing?', {
  validate: true,
  parse: true,
  schema: '{"summary": {"type": "string"}}'
});
```

--------------------------------

### Manage CLI Configuration

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Commands to inspect, validate, and retrieve system information for the GroundCite CLI.

```bash
# Show current configuration
gemini-groundcite config --show

# Validate configuration
gemini-groundcite config --validate

# Show version and system info
gemini-groundcite version
```

--------------------------------

### Schema Design: Good Practices

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Illustrates a well-designed JSON schema with clear types, descriptions, constraints, and `additionalProperties: False` to prevent unexpected fields.

```json
# ✅ Good schema design
good_schema = {
    "type": "object",
    "properties": {
        "summary": {
            "type": "string",
            "description": "Brief summary in 2-3 sentences"
        },
        "key_points": {
            "type": "array",
            "items": {"type": "string"},
            "maxItems": 10,
            "description": "Main points, max 10 items"
        },
        "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence score 0-1"
        }
    },
    "required": ["summary", "key_points"],
    "additionalProperties": False
}
```

--------------------------------

### Handle GroundCite Exceptions in Python

Source: https://context7.com/cennest/ground-cite/llms.txt

Demonstrates a robust pattern for catching specific library exceptions including configuration, AI agent, and graph execution errors.

```python
from gemini_groundcite.exceptions import (
    GroundCiteError,
    AIAgentError,
    ConfigurationError,
    GraphExecutionError
)
from gemini_groundcite.config.settings import AppSettings
from gemini_groundcite.core.agents import AIAgent
import asyncio

async def robust_analysis(query):
    """Analysis with comprehensive error handling."""
    try:
        settings = AppSettings()
        settings.ANALYSIS_CONFIG.query = query
        settings.AI_CONFIG.gemini_ai_key_primary = "your_key"

        # Validate configuration before proceeding
        is_valid, errors = settings.validate_all_configurations()
        if not is_valid:
            raise ConfigurationError(
                "Invalid configuration",
                {"errors": errors}
            )

        agent = AIAgent(settings=settings)
        result = await agent.analyze_query(max_retries=3)

        return result

    except ConfigurationError as e:
        # Raised when configuration is invalid or incomplete
        # - Missing API keys
        # - Invalid model configurations
        # - Missing required parameters
        print(f"Configuration error: {e.message}")
        print(f"Details: {e.details}")
        return None

    except AIAgentError as e:
        # Raised when errors occur during AI agent execution
        # - Model inference failures
        # - Pipeline execution issues
        print(f"AI Agent error: {e.message}")
        print(f"Details: {e.details}")
        return None

    except GraphExecutionError as e:
        # Raised when errors occur during graph execution pipeline
        # - Node execution failures
        # - State management issues
        print(f"Graph execution error: {e.message}")
        print(f"Details: {e.details}")
        return None

    except GroundCiteError as e:
        # Catch-all for any GroundCite library errors
        print(f"GroundCite error: {e.message}")
        print(f"Details: {e.details}")
        return None

    except Exception as e:
        # Unexpected errors
        print(f"Unexpected error: {e}")
        return None

# Usage
result = asyncio.run(robust_analysis("What is quantum computing?"))
if result:
    print("Analysis successful!")
```

--------------------------------

### Configure New AI Provider

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/CONTRIBUTING.md

Adding provider-specific settings to the AIConfig class.

```python
# In settings.py
class AIConfig:
    new_provider_api_key: str = ""
    new_provider_model_name: str = "default-model"
```

--------------------------------

### Enable verbose logging

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/USAGE.md

Configure the logging level to DEBUG to capture detailed execution information.

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

--------------------------------

### Model Configuration

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/API.md

Details on available models and their provider-specific parameters.

```APIDOC
## Model Configuration

### Available Models

#### Gemini Models
- `gemini-2.5-flash` - Fast, efficient model for most tasks
- `gemini-1.5-pro` - High-quality model for complex analysis
- `gemini-1.0-pro` - Balanced performance model

#### OpenAI Models
- `gpt-4` - High-quality general purpose model
- `gpt-4-turbo` - Fast, capable model
- `gpt-3.5-turbo` - Cost-effective option

### Provider-Specific Parameters

#### Gemini Parameters
```json
{
  "temperature": 0.7,          // Creativity level (0-1)
  "top_p": 0.9,               // Nucleus sampling
  "top_k": 40,                // Top-k sampling
  "max_output_tokens": 2048,   // Maximum response length
}
```

#### OpenAI Parameters
```json
{
  "temperature": 0.7,          // Creativity level (0-2)
  "max_tokens": 2048,          // Maximum response length
  "top_p": 1.0,               // Nucleus sampling
  "frequency_penalty": 0.0,    // Frequency penalty (0-2)
  "presence_penalty": 0.0,     // Presence penalty (0-2)
}
```
```

--------------------------------

### Request Initiation Data Flow

Source: https://github.com/cennest/ground-cite/blob/main/GroundCite/docs/ARCHITECTURE.md

Visual representation of the request initiation process through various interfaces.

```text
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    CLI      │    │  REST API   │    │ Python Lib  │
│ Interface   │    │  (FastAPI)  │    │   Direct    │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                          ▼
                 ┌─────────────┐
                 │ Configuration│
                 │  Validation │
                 └──────┬──────┘
                        │
                        ▼
                 ┌─────────────┐
                 │  AI Agent   │
                 │Orchestrator │
                 └──────┬──────┘
                        │
                        ▼
                 ┌─────────────┐
                 │   Graph     │
                 │  Executor   │
                 └──────┬──────┘
```