deep-research-client 0.1.2__tar.gz

deep_research_client-0.1.2/.claude/skills/README.md

@@ -0,0 +1,78 @@
+# Deep Research Client Skills
+
+This directory contains Claude Code skills for the deep-research-client project.
+
+## Available Skills
+
+### run-deep-research
+
+A comprehensive skill for performing deep research using multiple AI research providers (OpenAI, Falcon, Perplexity, Consensus).
+
+**Key Features:**
+- Support for multiple research providers with different speed/depth trade-offs
+- Smart caching to avoid expensive re-queries
+- Template-based research with variable substitution
+- Rich markdown output with citations and metadata
+
+**Installation:**
+
+To use this skill locally:
+
+```bash
+# Copy the skill to your local skills directory
+cp -r .claude/skills/run-deep-research ~/.claude/skills/
+```
+
+Or to use it project-wide, it's already available in `.claude/skills/run-deep-research/`.
+
+**Usage:**
+
+Once installed, Claude Code will automatically use this skill when you request deep research tasks. The skill will:
+
+1. Ask you to choose between fast/light or comprehensive/slow approaches
+2. Help you select the appropriate provider and model
+3. Execute the research query
+4. Save results with proper citations and metadata
+
+**Example prompts that trigger this skill:**
+- "Research the latest developments in CRISPR gene editing"
+- "I need a comprehensive analysis of quantum computing trends"
+- "Do a literature review on machine learning interpretability"
+- "Research gene TP53 in humans focusing on cancer associations"
+
+## Adding More Skills
+
+To add additional skills to this project:
+
+1. **Simple skill**: Create a single `.md` file like `skill-name.md` with YAML frontmatter:
+   ```yaml
+   ---
+   name: your-skill-name
+   description: Brief description of what your skill does (200 char max)
+   ---
+   ```
+
+2. **Complex skill** (with templates/examples): Create a directory with `SKILL.md`:
+   ```
+   .claude/skills/skill-name/
+   ├── SKILL.md          # Main skill with YAML frontmatter
+   └── examples/         # Optional supporting files
+       └── template.md
+   ```
+
+3. Add the skill instructions and documentation in the markdown body
+
+## Skill Development Guidelines
+
+When creating skills for this project:
+
+- Follow the YAML frontmatter format with `name` and `description`
+- Include clear "When to Use" sections
+- Provide concrete usage examples with `uv run` commands
+- Document all environment variables and configuration
+- Include workflow steps for Claude to follow
+- Add common patterns and use cases
+
+## License
+
+Skills in this directory are part of the deep-research-client project and follow the same BSD-3-Clause license.

deep_research_client-0.1.2/.claude/skills/gene-set-enrichment/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: gene-set-enrichment
+description: Perform gene set enrichment analysis using AI research providers. Analyzes lists of genes to identify biological themes, pathways, and functional associations.
+---
+
+# gene-set-enrichment
+
+Toolkit for performing gene set enrichment analysis on lists of genes using AI research providers. Identifies biological themes, pathways, diseases, and functional relationships within gene sets.
+
+## When to Use
+
+Use this skill when:
+- The user provides a list of genes and wants to understand what they have in common
+- The user needs pathway or functional enrichment analysis
+- The user wants to identify biological themes in differential expression results
+- The user needs to understand disease associations for a gene set
+- The user has genomic analysis results and wants biological interpretation
+
+## Default Configuration
+
+**This skill uses HEAVYWEIGHT mode by default:**
+- **Provider**: Perplexity
+- **Model**: `sonar-deep-research` 
+- **Rationale**: Extensive research is required to give meaningful results.
+
+Users can override to use comprehensive mode if needed for publication-quality analysis.
+
+## Features
+
+- **Pathway Analysis**: Identifies enriched biological pathways
+- **Disease Associations**: Finds disease connections for gene sets
+- **Functional Themes**: Discovers common biological functions
+- **Tissue Specificity**: Analyzes expression patterns across tissues
+- **Drug Targets**: Identifies potential therapeutic connections
+- **Template-Based**: Reusable template with space-separated gene lists
+
+## Required Environment Variables
+
+```bash
+# At least one is required:
+export PERPLEXITY_API_KEY="your-perplexity-key"   # Recommended for speed
+export OPENAI_API_KEY="your-openai-key"           # For comprehensive analysis
+export FUTUREHOUSE_API_KEY="your-futurehouse-key" # For scientific literature
+```
+
+## Basic Usage
+
+### Using the Template (Recommended)
+
+```bash
+# Quick enrichment analysis
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=APOH APP COL3A1 VEGFA THBD" \
+  --var "organism=human" \
+  --provider perplexity \
+  --model sonar-deep-research \
+  --output enrichment_results.md
+
+# Comprehensive analysis (slower, more detailed)
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=APOH APP COL3A1 VEGFA THBD" \
+  --var "organism=human" \
+  --provider openai \
+  --output enrichment_detailed.md
+```
+
+### Direct Query (No Template)
+
+```bash
+uv run deep-research-client research \
+  "Perform gene set enrichment analysis on: APOH APP COL3A1 VEGFA THBD. Identify common pathways, biological processes, and disease associations." \
+  --provider perplexity \
+  --model sonar-deep-research \
+  --output quick_enrichment.md
+```
+
+## Template Variables
+
+The enrichment template accepts:
+
+- `{geneset}` - **Space-separated** list of gene symbols (e.g., "APOH APP VEGFA")
+- `{organism}` - Organism name (e.g., "human", "mouse", "rat")
+- `{context}` - Optional: Study context (e.g., "upregulated in heart disease", "differentially expressed in cancer")
+
+## Workflow
+
+1. **Prepare gene list**: Convert gene list to space-separated format
+2. **Choose analysis mode**:
+   - Fast (sonar-pro): Quick exploratory analysis
+   - Comprehensive (openai): Publication-quality detailed analysis
+3. **Run template**: Use template with geneset variable
+4. **Review results**: Check identified pathways, functions, diseases
+5. **Iterate**: Refine analysis based on initial results
+
+## Output Format
+
+Results include:
+
+- **Enriched Pathways**: KEGG, Reactome, WikiPathways
+- **Biological Processes**: GO terms and functional categories
+- **Disease Associations**: OMIM, disease databases
+- **Tissue Expression**: Where genes are co-expressed
+- **Protein Interactions**: Known interaction networks
+- **Drug Connections**: Therapeutic targets and compounds
+- **Citations**: Links to relevant databases and publications
+
+## Example Gene Sets
+
+### Cardiovascular/ECM Example (36 genes)
+```
+APOH APP CND2 COL3A1 COL5A2 CXCL6 FGFR1 FSTL1 ITGAV JAG1 JAG2 KCNJ8 LPL LRPAP1 LUM MSX1 NRP1 OLR1 PDGFA PF4 PGLYRP1 POSTN PRG2 PTK2 S100A4 SERPINA5 SLCO2A1 SPP1 STC1 THBD TIMP1 TNFRSF21 VAV2 VCAN VEGFA VTN
+```
+
+This set appears enriched for:
+- Extracellular matrix organization
+- Cardiovascular development
+- Angiogenesis and vascular remodeling
+- Cell adhesion and migration
+
+### Small Test Set
+```
+TP53 BRCA1 BRCA2 PTEN RB1
+```
+
+Cancer-related tumor suppressors for testing.
+
+## Common Patterns
+
+### Quick exploratory enrichment
+```bash
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=GENE1 GENE2 GENE3" \
+  --var "organism=human" \
+  --provider perplexity \
+  --model sonar-pro
+```
+
+### Context-specific enrichment
+```bash
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=GENE1 GENE2 GENE3" \
+  --var "organism=human" \
+  --var "context=upregulated in diabetic cardiomyopathy" \
+  --var "focus=cardiac remodeling pathways"
+```
+
+### Comprehensive publication-quality
+```bash
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=GENE1 GENE2 GENE3" \
+  --var "organism=human" \
+  --provider openai
+```
+
+## Tips for Best Results
+
+1. **Gene Symbol Format**: Use official gene symbols (HUGO for human, MGI for mouse)
+2. **List Size**: Works best with 10-500 genes
+   - Too few (<5): Limited statistical power
+   - Too many (>1000): May be too broad
+3. **Organism**: Specify organism to avoid ambiguity
+4. **Context**: Add experimental context for more relevant results
+5. **Iteration**: Start with fast mode, then use comprehensive for final analysis
+6. **Caching**: Results are cached - use `--no-cache` to force re-analysis with updated databases
+
+## Integration with Analysis Pipelines
+
+### From differential expression results
+```python
+# Python example: extract top genes
+import pandas as pd
+
+# Load DEG results
+degs = pd.read_csv("deg_results.csv")
+top_genes = degs[degs['padj'] < 0.05].head(50)['gene_symbol'].tolist()
+geneset = " ".join(top_genes)
+
+# Use with template
+print(f"--var \"geneset={geneset}\"")
+```
+
+### From genomic analysis
+```bash
+# Extract gene symbols from analysis output
+cut -f1 significant_genes.txt | tr '\n' ' ' > geneset.txt
+
+# Use in template
+uv run deep-research-client research \
+  --template .claude/skills/gene-set-enrichment/examples/enrichment_template.md \
+  --var "geneset=$(cat geneset.txt)" \
+  --var "organism=human"
+```
+
+## Comparison with Traditional Tools
+
+This AI-based approach complements traditional enrichment tools (DAVID, Enrichr, g:Profiler):
+
+**Advantages:**
+- Natural language interpretation
+- Integrated cross-database search
+- Literature context and recent discoveries
+- Flexible, conversational analysis
+
+**Traditional Tools Still Better For:**
+- Precise statistical p-values
+- Large-scale batch processing
+- Specific database versions
+- Reproducible computational workflows
+
+**Best Practice**: Use both approaches:
+1. Run traditional enrichment for statistics
+2. Use this skill for biological interpretation and context
+
+## Important Notes
+
+- **Default is fast mode**: Uses sonar-pro for quick results
+- **Gene symbols**: Use standard nomenclature (HGNC for human)
+- **List format**: Space-separated gene symbols in the template variable
+- **Caching**: Results cached by gene set and provider
+- **Updates**: AI models have knowledge cutoff - very recent discoveries may not be included
+- **Validation**: Cross-reference with traditional enrichment tools for important findings
+
+## Related Skills
+
+- **run-deep-research**: For individual gene deep-dive analysis
+- Custom analysis workflows can combine both skills

deep_research_client-0.1.2/.claude/skills/gene-set-enrichment/examples/enrichment_template.md

@@ -0,0 +1,22 @@
+# Gene Set Enrichment Analysis
+
+Please perform a comprehensive gene set enrichment analysis on the following list of genes from {organism}.
+
+## Gene Set
+
+{geneset}
+
+## Analysis Context
+
+{context}
+
+
+## Output Requirements
+
+Please provide:
+
+- **Summary**: 2-3 sentence overview of the main biological themes
+- **Top Pathways**: List of most significant pathways with descriptions
+- **Biological Interpretation**: Integrated biological interpretation of the gene set
+- **Literature Support**: Recent relevant publications (last 5 years preferred)
+- **Database Links**: Links to relevant pathway/disease databases where appropriate

deep_research_client-0.1.2/.claude/skills/run-deep-research/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: run-deep-research
+description: Toolkit for performing deep research on complex topics using multiple AI research providers (OpenAI, Falcon, Perplexity, Consensus). Emphasizes explicit speed vs depth trade-offs.
+---
+
+# run-deep-research
+
+Toolkit for performing deep research on complex topics using multiple AI research providers including OpenAI Deep Research, FutureHouse Falcon, Perplexity AI, and Consensus AI.
+
+## When to Use
+
+Use this skill when:
+- The user requests comprehensive research on a topic
+- The user needs citations and sources for their research
+- The user wants to explore scientific literature or academic papers
+- The user needs structured markdown reports with metadata
+
+## CRITICAL: Speed vs Depth Trade-offs
+
+**ALWAYS** ask the user to be explicit about their approach preference:
+
+### Fast/Light Approach (seconds to complete)
+- **Provider**: Perplexity
+- **Models**: `sonar`, `sonar-pro`, `sonar-reasoning`, `sonar-reasoning-pro`
+- **Use when**: Quick answers, initial exploration, time-sensitive queries
+- **Cost**: Lower API costs
+- **Example**:
+  ```bash
+  uv run deep-research-client research "What is CRISPR?" --provider perplexity --model sonar-pro
+  ```
+
+### Comprehensive/Slow Approach (minutes to complete)
+- **Provider**: Perplexity with deep research model, or OpenAI
+- **Models**: `sonar-deep-research` (Perplexity), `o3-deep-research-2025-06-26` (OpenAI)
+- **Use when**: Thorough analysis needed, critical decisions, comprehensive reports
+- **Cost**: Higher API costs and longer wait times
+- **Example**:
+  ```bash
+  uv run deep-research-client research "What is CRISPR?" --provider perplexity --model sonar-deep-research
+  ```
+  or
+  ```bash
+  uv run deep-research-client research "What is CRISPR?" --provider openai
+  ```
+
+### Specialized Approaches
+- **Scientific Literature**: Use `falcon` provider for academic/scientific focus
+- **Academic Papers**: Use `consensus` provider for peer-reviewed research (requires API approval)
+
+## Features
+
+- **Multiple Providers**: OpenAI Deep Research, FutureHouse Falcon, Perplexity AI, Consensus AI
+- **Rich Output**: Comprehensive markdown reports with citations and YAML frontmatter metadata
+- **Smart Caching**: File-based caching in `~/.deep_research_cache/` to avoid expensive re-queries
+- **Auto-detection**: Automatically detects available providers from environment variables
+- **Templates**: Support for reusable research queries with variable substitution
+- **Citation Management**: Citations included by default or saved to separate file
+
+## Required Environment Variables
+
+```bash
+# At least one of these is required:
+export OPENAI_API_KEY="your-openai-key"           # For OpenAI Deep Research
+export FUTUREHOUSE_API_KEY="your-futurehouse-key" # For Falcon
+export PERPLEXITY_API_KEY="your-perplexity-key"   # For Perplexity AI
+export CONSENSUS_API_KEY="your-consensus-key"     # For Consensus AI (requires approval)
+```
+
+## Basic Usage
+
+### Simple Research Query
+```bash
+# Basic query (uses auto-detected provider)
+uv run deep-research-client research "What is quantum computing?"
+
+# With specific provider and model
+uv run deep-research-client research "What is quantum computing?" --provider perplexity --model sonar-pro
+
+# Save to file
+uv run deep-research-client research "Machine learning trends 2024" --output report.md
+```
+
+### List Available Providers
+```bash
+uv run deep-research-client providers
+```
+
+### Using Templates
+Templates allow reusable research queries with variable substitution:
+
+```bash
+# Use template with variables
+uv run deep-research-client research \
+  --template gene_research.md \
+  --var "gene=TP53" \
+  --var "organism=human" \
+  --var "tissue=brain tissue" \
+  --var "year=2020"
+```
+
+Template files use `{variable}` placeholders:
+```markdown
+Please research the gene {gene} in {organism}, focusing on:
+1. Function and molecular mechanisms
+2. Disease associations in {tissue} tissue
+3. Recent discoveries since {year}
+```
+
+### Cache Management
+```bash
+# List cached research
+uv run deep-research-client list-cache
+
+# Clear all cache
+uv run deep-research-client clear-cache
+
+# Bypass cache for single query
+uv run deep-research-client research "query" --no-cache
+```
+
+## Output Format
+
+Research results are returned as markdown with YAML frontmatter:
+
+```yaml
+---
+provider: perplexity
+model: sonar-pro
+cached: false
+start_time: '2025-10-18T17:43:49.437056'
+end_time: '2025-10-18T17:44:08.922200'
+duration_seconds: 19.49
+citation_count: 18
+---
+
+## Question
+
+What is machine learning?
+
+## Output
+
+**Machine learning** is a branch of artificial intelligence...
+
+## Citations
+
+1. https://www.ibm.com/topics/machine-learning
+2. https://www.coursera.org/articles/what-is-machine-learning
+```
+
+## Model Selection Guide
+
+| Provider | Default Model | Alternative Models | Speed | Depth | Best For |
+|----------|---------------|-------------------|-------|-------|----------|
+| **Perplexity** | `sonar-deep-research` | `sonar`, `sonar-pro`, `sonar-reasoning`, `sonar-reasoning-pro` | Pro models: Fast | Deep Research: Comprehensive | Real-time web search |
+| **OpenAI** | `o3-deep-research-2025-06-26` | - | Slow | Very Comprehensive | Thorough analysis |
+| **Falcon** | Default API | - | Medium | Scientific | Academic/scientific literature |
+| **Consensus** | Default API | - | Medium | Academic | Peer-reviewed papers |
+
+## Workflow
+
+1. **Ask user for speed preference**: Always clarify if they want fast/light or comprehensive/slow approach
+2. **Check environment variables**: Ensure appropriate API keys are set
+3. **Run research**: Use `uv run deep-research-client research` with appropriate provider and model
+4. **Save output**: Use `--output` flag to save to file if needed
+5. **Review results**: Check the markdown output, citations, and metadata
+6. **Cache management**: Be aware that results are cached permanently unless cleared
+
+## Important Notes
+
+- **Cost awareness**: Deep research models can be expensive - always confirm with user before using
+- **Time awareness**: Deep research can take several minutes - warn user about expected wait time
+- **Caching**: Results are cached permanently in `~/.deep_research_cache/` - use `--no-cache` to bypass
+- **Citations**: Always included by default; use `--separate-citations` to save to separate file
+- **Templates**: Great for repeated research patterns (e.g., gene research, company analysis)
+- **Metadata**: YAML frontmatter includes timing, provider info, and configuration details
+
+## Common Patterns
+
+### Quick exploratory research
+```bash
+uv run deep-research-client research "overview of topic X" --provider perplexity --model sonar-pro --output quick-research.md
+```
+
+### Comprehensive deep dive
+```bash
+uv run deep-research-client research "comprehensive analysis of topic X" --provider openai --output deep-research.md
+```
+
+### Scientific literature review
+```bash
+uv run deep-research-client research "scientific review of topic X" --provider falcon --output scientific-review.md
+```
+
+### Template-based gene research
+```bash
+uv run deep-research-client research --template gene_research.md --var "gene=BRCA1" --var "organism=human" --output brca1-research.md
+```
+
+## Python Library Usage
+
+```python
+from deep_research_client import DeepResearchClient
+
+# Initialize client (auto-detects providers from env vars)
+client = DeepResearchClient()
+
+# Perform research
+result = client.research(
+    "What are the latest developments in AI?",
+    provider="perplexity",
+    model="sonar-pro"
+)
+
+print(result.markdown)  # Full markdown report
+print(f"Provider: {result.provider}")
+print(f"Model: {result.model}")
+print(f"Duration: {result.duration_seconds:.2f}s")
+print(f"Citations: {len(result.citations)}")
+print(f"Cached: {result.cached}")
+```

deep_research_client-0.1.2/.claude/skills/run-deep-research/examples/gene_research.md

@@ -0,0 +1,38 @@
+# Gene Research Template
+
+Please research the gene {gene} in {organism}, providing a comprehensive analysis focusing on:
+
+## Requested Analysis
+
+1. **Molecular Function and Mechanisms**
+   - Primary molecular function
+   - Key protein interactions
+   - Cellular localization
+   - Post-translational modifications
+
+2. **Disease Associations**
+   - Known disease associations
+   - Mutation effects and pathogenicity
+   - Clinical significance
+   - Therapeutic implications
+
+3. **Expression Patterns**
+   - Tissue-specific expression
+   - Expression in {tissue}
+   - Developmental regulation
+   - Expression changes in disease states
+
+4. **Recent Discoveries**
+   - Key findings since {year}
+   - Novel therapeutic approaches
+   - Emerging research directions
+   - Clinical trials and applications
+
+## Search Parameters
+
+- Gene: {gene}
+- Organism: {organism}
+- Tissue of Interest: {tissue}
+- Time Frame: Research since {year}
+
+Please provide comprehensive citations from peer-reviewed sources and include links to relevant databases (NCBI Gene, UniProt, ClinVar, etc.) where appropriate.

deep_research_client-0.1.2/.copier-answers.yml

@@ -0,0 +1,14 @@
+# Changes here will be overwritten by Copier
+_commit: 08e42af
+_src_path: monarch-project-copier
+copyright_year: '2025'
+email: my-name@my-org.org
+full_name: My Name
+gh_action_docs_preview: false
+github_handle: cmungall
+github_org: ai4curation
+license: BSD-3-Clause
+project_description: Wrapper for multiple deep research tools
+project_name: deep-research-client
+project_slug: deep_research_client
+

deep_research_client-0.1.2/.editorconfig

@@ -0,0 +1,18 @@
+# Check http://editorconfig.org for more information
+# This is the main config file for this project:
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false