Metadata-Version: 2.4
Name: gffutilsai
Version: 0.1.4
Summary: Using gffutil Python module with AI
License-Expression: GPL-3.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gffutils>=0.13
Requires-Dist: strands-agents[anthropic,ollama]>=1.10.0
Requires-Dist: strands-agents-tools>=0.2.9
Requires-Dist: biopython>=1.85
Dynamic: license-file

# GFF Analysis Tools - AI Agent

A comprehensive bioinformatics AI agent for analyzing GFF (General Feature Format) files using natural language queries. This project extends a basic GFF analysis agent with advanced querying capabilities, statistical analysis, and data export features.

## Overview

This AI agent provides an intuitive interface for bioinformatics researchers to analyze GFF files without writing complex code. Users can ask questions in natural language, and the agent will select and execute the appropriate analysis tools to provide comprehensive answers.

## Features

### 🧬 Coordinate-based Queries
- Find features by genomic coordinates (regions and specific positions)
- Query features overlapping genomic regions with filtering by type and strand
- Identify features containing specific genomic positions

### 🔗 Relationship and Hierarchy Analysis
- Explore gene structure and organization (get all child features like exons, CDS, UTRs)
- Find parent features of any given feature using upward traversal
- Get all features of specific types with efficient iteration

### 📊 Statistical Analysis
- Calculate comprehensive feature statistics (counts, length distributions per feature type)
- Generate per-chromosome feature summaries and analysis
- Analyze length distributions with detailed statistics (min, max, mean, median, std dev, percentiles)
- Create histogram data for feature length distributions

### 🔍 Attribute-based Searches
- Search features by attribute key-value pairs (exact and partial matching)
- Find features containing specific attribute keys
- Support pattern matching and logical operations for attribute queries

### 📍 Positional Analysis
- Identify intergenic regions (gaps between genes) with filtering options
- Calculate feature density in genomic windows across chromosomes
- Analyze strand distribution of features with counts and percentages
- Support clustering analysis and positional insights

### 📤 Export and Reporting
- Export feature data to CSV format with comprehensive filtering
- Generate human-readable summary reports of GFF file contents
- Provide formatted output for downstream analysis

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install gffutilsai
```

After installation, you can use the command:

```bash
gffai --help
```

### Option 2: Development Installation

#### Prerequisites

- Python 3.12+
- Ollama (for running local LLM models)

#### Dependencies

Install the required Python packages:

```bash
pip install gffutils strands requests
```

### Ollama Setup

1. Install Ollama from [https://ollama.ai](https://ollama.ai)
2. Pull a compatible model (e.g., llama3.1):
   ```bash
   ollama pull llama3.1
   ```
3. Ensure Ollama is running on `http://localhost:11434`

## Usage

### Running the Agent

#### Basic Usage (Interactive Mode)

**If installed via pip:**
```bash
# Use default settings (llama3.1 model on local server)
gffai

# Use cloud server with default model (gpt-oss:20b-cloud)
gffai --server cloud

# Use Anthropic Claude model (default: claude-3-5-haiku-latest)
gffai --anthropic

# Specify custom model and server
gffai --model llama3.1 --server local
gffai --model codellama:13b --server local
gffai --model gpt-4 --server cloud
gffai --anthropic --model claude-3-5-sonnet-latest
```

**If running from source:**
```bash
# Use default settings (llama3.1 model on local server)
python main.py

# Use cloud server with default model (gpt-oss:20b-cloud)
python main.py --server cloud

# Use Anthropic Claude model (default: claude-3-5-haiku-latest)
python main.py --anthropic
```

If you are going to use a cloud model you need to export the api key.

For Ollama:

```
export OLLAMA_API_KEY="XXXXXXXXXXXXXX"
```

For Anthropic:

```
export ANTHROPIC_API_KEY="XXXXXXXXXXXXX"
```


#### Single Query Mode

```bash
# Run a single query and exit
python main.py --query "What feature types are in my GFF file?"
python main.py --model llama3.1 --query "Find all genes on chromosome 1"
```

#### Command Line Options

- `--model, -m`: Model to use (default: llama3.1 for local, gpt-oss:20b-cloud for cloud)
- `--server, -s`: Server type - 'local' or 'cloud' (default: local)
- `--anthropic`: Use Anthropic Claude model (default: claude-3-5-haiku-latest)
- `--host`: Custom host URL (overrides --server setting)
- `--query, -q`: Run a single query and exit
- `--temperature, -t`: Temperature for responses (0.0-1.0, default: 0.1)
- `--max-tokens`: Maximum tokens for responses (default: 4096)
- `--system-prompt`: Path to system prompt file (default: system_prompt.txt)
- `--debug`: Show detailed debug information including tool calls and parameters

#### Server Options

**Local Server (default):**
- Uses `http://localhost:11434`
- Requires Ollama running locally
- Free and private

**Cloud Server:**
- Uses `https://ollama.com`
- Requires `OLLAMA_API_KEY` environment variable
- May have usage costs
- **Security restriction**: `file_read` tool is disabled for security

**Anthropic Claude:**
- Uses Anthropic's Claude models via API
- Requires `ANTHROPIC_API_KEY` environment variable
- **Security restriction**: `file_read` tool is disabled for security
- Default model: `claude-3-5-haiku-latest`

The agent will start in interactive mode where you can ask questions about your GFF files, or use `--query` for single commands.

### Example Queries

Here are some example questions you can ask the agent:

#### Basic Information
- "What feature types are available in my GFF file?"
- "How many genes are in chromosome 1?"
- "What's the length of gene AT1G01010?"

#### Coordinate-based Queries
- "Find all genes in chromosome 1 between positions 1000-5000"
- "What features are at position 2500 on chromosome 2?"
- "Show me all exons on the positive strand in the region chr1:10000-20000"

#### Gene Structure Analysis
- "Get the structure of gene AT1G01010 including all exons and CDS"
- "What are the parent features of exon AT1G01010.1?"
- "Show me all CDS features in the genome"

#### Statistical Analysis
- "Calculate feature statistics for this GFF file"
- "What's the length distribution of genes?"
- "Give me a summary of features on each chromosome"

#### Attribute Searches
- "Find all features with 'kinase' in their Name attribute"
- "Show me features that have a Note attribute"
- "Search for genes with 'hypothetical' in their description"

#### Positional Analysis
- "Identify intergenic regions longer than 1000bp on chromosome 2"
- "Calculate gene density in 10kb windows across chromosome 1"
- "What's the strand distribution of genes?"

#### Data Export
- "Export all exon features to CSV format"
- "Generate a summary report of this GFF file"
- "Save gene information to a CSV file"

#### Sample session


```
$ uv run python src/gffutilsAI/main.py -s cloud -m glm-4.6:cloud
🤖 GFF Analysis AI Agent
📊 Model: glm-4.6:cloud
🌐 Server: cloud (https://ollama.com)
🌡️  Temperature: 0.1
--------------------------------------------------
📝 System prompt loaded from: system_prompt.txt
🔒 Cloud server: file_read tool disabled for security
💬 Interactive mode - Type your questions about GFF files
   Type 'quit' or 'exit' to stop
--------------------------------------------------

🧬 GFF Query: list files in src/gffutilsAI/data/
------------------------------

Tool #1: list_directory
The directory `src/gffutilsAI/data/` contains the following files:

1. **GCF_040556925.1_ASM4055692v1_genomic.gff**
2. **subset_4percent.gff**

Both appear to be GFF (General Feature Format) files, which are commonly used for genome annotation data. Would you like me to analyze either of these files or perform any specific operations on them?
------------------------------

🧬 GFF Query: how many chromosomes are there in GCF_040556925.1_ASM4055692v1_genomic.gff
------------------------------

Tool #2: get_chromosomes_info
The GFF file `GCF_040556925.1_ASM4055692v1_genomic.gff` contains **1 chromosome**:

- **NZ_CP159789.1**

This appears to be a bacterial genome assembly, as indicated by the "NZ_CP" prefix which is typically used for RefSeq complete bacterial genomes.
------------------------------

🧬 GFF Query: which species it is?
------------------------------

Tool #3: get_organism_info
The GFF file `GCF_040556925.1_ASM4055692v1_genomic.gff` contains the genome of **Mycoplasmoides genitalium**, which is a bacterial species (taxonomy ID: 2097).

This is consistent with the fact that there's only one chromosome (NZ_CP159789.1) in the file, as bacteria typically have a single circular chromosome.
------------------------------

🧬 GFF Query: how many genes there are?
------------------------------

Tool #4: get_feature_statistics
The Mycoplasmoides genitalium genome contains **545 genes**.

Here's a breakdown of the genomic features in this assembly:

- **Genes**: 545
- **CDS (coding sequences)**: 524
- **Pseudogenes**: 21
- **tRNA**: 36
- **rRNA**: 3
- **Other RNA features**: 4 (RNase_P_RNA, SRP_RNA, tmRNA)
- **Exons**: 42
- **Total features**: 1,175

The genome has a total length of 1,706,785 base pairs (~1.7 Mb), which is typical for Mycoplasma species, which have some of the smallest known bacterial genomes.
------------------------------

🧬 GFF Query: how many membrane genes? 
------------------------------

Tool #5: search_genes_by_go_function_attribute

Tool #6: search_genes_by_go_function_attribute

Tool #7: search_genes_by_go_function_attribute

Tool #8: search_genes_by_go_function_attribute

Tool #9: search_features_by_attribute

Tool #10: search_features_by_attribute
Based on my analysis of the Mycoplasmoides genitalium genome, I found **approximately 35-40 membrane-related genes**. Here's the breakdown:

## Membrane Genes Found:

### Transporters (Primary Category):
- **ABC transporters**: ~20 genes (ATP-binding proteins, permeases, substrate-binding proteins)
- **Energy-coupling factor (ECF) transporters**: ~5 genes
- **MFS transporters**: 1 gene
- **MATE family efflux transporter**: 1 gene
- **PTS transporters**: ~3 genes (phosphotransferase system)

### Other Membrane Proteins:
- **Membrane protein insertase YidC**: 1 gene
- **Lysylphosphatidylglycerol synthase**: 1 gene (membrane domain-containing)
- **Replication initiation and membrane attachment protein**: 1 gene

## Key Findings:
- **Total membrane-related genes**: ~35-40 out of 545 total genes (~6-7% of genome)
- **Transporters dominate**: ~30 genes are involved in various transport processes
- **ABC transporters are most abundant**: ~20 genes for importing nutrients and exporting waste
- **ECF transporters**: Specialized for vitamin and micronutrient uptake

This is typical for Mycoplasma species, which have reduced genomes and rely heavily on transport systems to import nutrients from their host environment since they lack many metabolic pathways.
------------------------------

🧬 GFF Query: can you write a CSV file with gene name, position and description? call it membrane_genes.csv
------------------------------

Tool #11: file_write
I've successfully created the CSV file `membrane_genes.csv` with **37 membrane-related genes** from the Mycoplasmoides genitalium genome. The file contains:

**Columns:**
- `gene_name`: Locus tag (e.g., ABS333_RS00080)
- `chromosome`: Chromosome identifier (NZ_CP159789.1)
- `start`: Start position in the genome
- `end`: End position in the genome  
- `description`: Protein description

**Summary of the data:**
- **37 total membrane genes** included
- **ABC transporters**: 20 genes (most abundant category)
- **ECF transporters**: 5 genes
- **PTS transporters**: 3 genes
- **Other membrane proteins**: 9 genes (including YidC, MFS transporter, MATE efflux transporter, etc.)

The file is now ready for use in downstream analysis, visualization, or further bioinformatics work. You can open it in Excel, R, Python, or any spreadsheet program to work with the membrane gene data.
------------------------------

```

## Configuration

### Model Configuration

#### Command Line Configuration (Recommended)

Configure the model and server using command line arguments:

```bash
# Local server with different models
python main.py --model llama3.1 --server local
python main.py --model codellama:13b --server local
python main.py --model mistral:7b --server local

# Cloud server with default model (gpt-oss:20b-cloud)
export OLLAMA_API_KEY="your-api-key-here"
python main.py --server cloud

# Cloud server with custom model
export OLLAMA_API_KEY="your-api-key-here"
python main.py --model gpt-4 --server cloud

# Anthropic Claude with default model (claude-3-5-haiku-latest)
export ANTHROPIC_API_KEY="your-anthropic-api-key"
python main.py --anthropic

# Anthropic Claude with custom model
export ANTHROPIC_API_KEY="your-anthropic-api-key"
python main.py --anthropic --model claude-3-5-sonnet-latest

# Custom settings
python main.py --model llama3.1 --temperature 0.3 --max-tokens 2048

# Use custom system prompt
python main.py --system-prompt my_custom_prompt.txt

# Enable debug mode to see tool calls and parameters
python main.py --debug --query "What features are in my GFF file?"
```

#### Environment Variables

For cloud server usage, set your API key:

```bash
export OLLAMA_API_KEY="your-ollama-api-key"
```

For Anthropic Claude usage, set your API key:

```bash
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```

#### Available Models

**Local Models** (require `ollama pull <model>`):
- `llama3.1` - General purpose, good balance
- `codellama:13b` - Code-focused, good for technical queries
- `mistral:7b` - Faster, lighter model
- `llama2:70b` - Larger, more capable (requires more resources)

**Cloud Models** (via ollama.com):
- `gpt-oss:20b-cloud` - Default cloud model, good balance of capability and speed
- `gpt-4` - Most capable, requires API key
- `gpt-3.5-turbo` - Fast and capable
- Various other models available through the service

**Anthropic Claude Models**:
- `claude-3-5-haiku-latest` - Default Anthropic model, fast and efficient
- `claude-3-5-sonnet-latest` - More capable, balanced performance
- `claude-3-opus-latest` - Most capable Claude model
- Various other Claude models available

### Database Management

The agent automatically creates and manages GFF databases:
- First query creates a database file named after your GFF file (e.g., `file.gff` → `file.db`)
- Subsequent queries reuse the existing database for faster performance
- Database files are created in the same directory as the GFF file
- Multiple GFF files can have their own separate database files

## Project Structure

```
├── main.py              # Main application with CLI interface and agent setup
├── gff_tools.py         # All GFF analysis tool functions
├── system_prompt.txt    # Editable system prompt for the AI agent
├── README.md            # This documentation
└── .kiro/specs/         # Development specifications (optional)
```

## Available Tools

The agent has access to 18+ specialized tools for GFF analysis (defined in `gff_tools.py`):

### File Operations
- `file_read` - Read and display file contents (local server only)
- `file_write` - Write content to files
- `list_directory` - List directory contents

### GFF Analysis Tools
- `get_gff_feature_types` - Get all available feature types
- `get_gene_length` - Get length of specific genes
- `get_multiple_gene_length` - Get lengths of multiple genes
- `get_gene_attributes` - Get gene attributes (ID, Name, Note, etc.)
- `get_features_in_region` - Find features in genomic regions
- `get_features_at_position` - Find features at specific positions
- `get_gene_structure` - Get gene structure with child features
- `get_feature_parents` - Find parent features
- `get_features_by_type` - Get all features of a specific type
- `get_feature_statistics` - Calculate comprehensive statistics
- `get_chromosome_summary` - Per-chromosome analysis
- `get_length_distribution` - Length distribution analysis
- `search_features_by_attribute` - Search by attributes
- `get_features_with_attribute` - Find features with specific attributes
- `get_intergenic_regions` - Identify gaps between genes
- `get_feature_density` - Calculate feature density in windows
- `get_strand_distribution` - Analyze strand distribution
- `export_features_to_csv` - Export data to CSV
- `get_feature_summary_report` - Generate summary reports

## File Formats

### Input
- **GFF3 files** - Standard GFF3 format with proper feature hierarchies
- **GFF2 files** - Older GFF format (limited support)

### Output
- **CSV** - Tabular data export with all feature information
- **JSON** - Structured data format (via agent responses)
- **Text Reports** - Human-readable summaries and statistics

## Performance Considerations

- **Database Creation**: First analysis of a GFF file creates a database, which may take time for large files
- **Memory Usage**: Large GFF files may require significant memory for analysis
- **Result Limiting**: Tools support limiting results for very large datasets
- **Database Reuse**: Subsequent queries on the same GFF file are much faster

### Help and Examples

Get help with command line options:

```bash
python main.py --help
```

Example commands:

```bash
# Interactive mode with local llama3.1
python main.py

# Interactive mode with cloud default model (gpt-oss:20b-cloud)
export OLLAMA_API_KEY="your-key"
python main.py --server cloud

# Interactive mode with cloud GPT-4
export OLLAMA_API_KEY="your-key"
python main.py --model gpt-4 --server cloud

# Interactive mode with Anthropic Claude
export ANTHROPIC_API_KEY="your-anthropic-key"
python main.py --anthropic

# Single query mode
python main.py --query "What chromosomes are in my GFF file?" --model llama3.1

# Custom temperature for more creative responses
python main.py --temperature 0.5 --model codellama:13b

# Custom host
python main.py --host "http://my-server:8080" --model custom-model
```

## Troubleshooting

### Common Issues

1. **"File not found" errors**
   - Ensure GFF file path is correct
   - Check file permissions

2. **Database creation fails**
   - Verify GFF file format is valid
   - Check available disk space
   - Ensure write permissions in current directory

3. **Ollama connection errors**
   - Verify Ollama is running: `ollama list`
   - Check if model is available: `ollama pull llama3.1`
   - Ensure correct host URL in configuration

4. **Memory issues with large files**
   - Use result limiting parameters where available
   - Consider analyzing subsets of data
   - Increase system memory if possible

### Debug Mode

Use the `--debug` flag to see detailed information about tool execution:

```bash
# Enable debug mode for single query
python main.py --debug --query "What features are in my GFF file?"

# Enable debug mode for interactive session
python main.py --debug

# Debug with specific model
python main.py --debug --anthropic --query "Analyze my GFF file"
```

Debug mode shows:
- **Model Information**: Which model and parameters were used
- **Tool Calls**: Which tools were executed and with what parameters
- **Tool Results**: Preview of tool outputs (truncated for readability)
- **Performance Metrics**: Token usage and execution time (when available)
- **Error Details**: Full stack traces for troubleshooting

## Development

### Adding New Tools

To add new GFF analysis tools:

1. Add your tool function to `gff_tools.py` with the `@tool` decorator
2. Import the new tool in `main.py`
3. Add it to the `tools` list in the Agent initialization
4. Update `system_prompt.txt` to describe the new capability

### Customizing the System Prompt

The AI agent's behavior is controlled by the system prompt in `system_prompt.txt`. You can:

1. **Edit the default prompt**: Modify `system_prompt.txt` directly
2. **Use a custom prompt file**: `python main.py --system-prompt my_custom_prompt.txt`
3. **Customize for specific use cases**: Create different prompt files for different analysis workflows

The system prompt defines:
- The agent's personality and communication style
- Available capabilities and how to describe them
- Example queries users can ask
- Guidelines for tool usage and error handling

### Project Architecture

- **main.py**: Entry point with CLI argument parsing, model configuration, and agent setup
- **gff_tools.py**: All tool functions decorated with `@tool` for the AI agent to use
- **Modular Design**: Tools are separated from the main application logic for better maintainability

## Contributing

This project follows a specification-driven development approach. See the `.kiro/specs/gff-analysis-tools/` directory for:
- `requirements.md` - Feature requirements
- `design.md` - Technical design
- `tasks.md` - Implementation tasks

## License

GPL-3.0

## Acknowledgments

- Built with [gffutils](https://github.com/daler/gffutils) for GFF file parsing
- Powered by [Strands](https://github.com/weaviate/strands) AI agent framework
- Uses [Ollama](https://ollama.ai) for local LLM inference

## Support

For issues and questions:

sebastian@toyoko.io
