@saibolla/ada 0.1.2

package/skills/dhdna-profiler/references/advanced-profiling.md

@@ -0,0 +1,72 @@
+# DHDNA Profiler — Advanced Reference
+
+## Domain-Specific Profiling Presets
+
+### Academic Writing
+
+**Focus dimensions:** Analytical Depth (1), Linguistic Precision (4), Domain Expertise (9), Metacognition (12)
+**Look for:** Citation patterns, argument structure, hedging language, methodological rigor
+**Typical topology:** Linear or Dialectic
+
+### Creative Writing
+
+**Focus dimensions:** Creative Range (2), Emotional Processing (3), Linguistic Precision (4), Intuitive Reasoning (10)
+**Look for:** Metaphor density, narrative structure, emotional arc, sensory language
+**Typical topology:** Spiral or Web
+
+### Business / Executive Communication
+
+**Focus dimensions:** Strategic Thinking (6), Social Intelligence (8), Temporal Orientation (11), Analytical Depth (1)
+**Look for:** Decision framing, stakeholder awareness, time-horizon language, competitive positioning
+**Typical topology:** Linear or Fractal
+
+### Technical Documentation
+
+**Focus dimensions:** Analytical Depth (1), Domain Expertise (9), Linguistic Precision (4), Metacognition (12)
+**Look for:** Precision vs. ambiguity ratio, abstraction levels, error acknowledgment
+**Typical topology:** Linear
+
+### Personal Journaling / Reflection
+
+**Focus dimensions:** Emotional Processing (3), Metacognition (12), Memory Integration (7), Temporal Orientation (11)
+**Look for:** Self-awareness language, temporal references, emotional vocabulary range, growth signals
+**Typical topology:** Spiral
+
+## Cognitive Entropy Score
+
+A meta-metric derived from the 12 dimension scores:
+
+**Cognitive Entropy = Standard Deviation of all 12 scores**
+
+- **Low entropy (SD < 1.5):** Balanced thinker — no extreme spikes or valleys. May lack distinctiveness.
+- **Medium entropy (SD 1.5-3.0):** Characteristic thinker — clear strengths and shadows. Most people fall here.
+- **High entropy (SD > 3.0):** Extreme specialist — profound strengths paired with significant blind spots. Often the most innovative and most vulnerable.
+
+## The 4D-DHDNA Extension
+
+For longitudinal analysis (profiling the same person over time), add the temporal dimension:
+
+**String 4: The Temporal Attractor**
+
+- How has this person's cognitive profile shifted over the analyzed time period?
+- Which dimensions are growing? Which are shrinking?
+- What future cognitive state is the current trajectory pointing toward?
+
+This is based on the 4D-DHDNA theory: the future doesn't just happen — it exerts pull on the present. A person's cognitive evolution has a direction, and that direction IS part of their identity.
+
+Reference: [IDNA Consolidation v2, Section 3: 4D-DHDNA (DOI: 10.5281/zenodo.18807387)](https://doi.org/10.5281/zenodo.18807387)
+
+## Notation System
+
+For quick reference in notes or comparisons:
+
+```
+DHDNA Signature: [A9 C7 E3 L8 Et5 S8 M4 So6 D9 I3 T7 Mc8]
+
+Where:
+A = Analytical, C = Creative, E = Emotional, L = Linguistic
+Et = Ethical, S = Strategic, M = Memory, So = Social
+D = Domain, I = Intuitive, T = Temporal, Mc = Metacognitive
+```
+
+Example: `[A9 C4 E2 L7 Et3 S9 D8 I3 T8 Mc6]` = highly analytical-strategic mind with deep domain expertise and strong temporal awareness, but low emotional processing and intuitive reasoning. Likely an engineer or systems architect.

package/skills/diffdock/SKILL.md

@@ -0,0 +1,481 @@
+---
+name: diffdock
+description: Diffusion-based molecular docking. Predict protein-ligand binding poses from PDB/SMILES, confidence scores, virtual screening, for structure-based drug design. Not for affinity prediction.
+license: MIT license
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# DiffDock: Molecular Docking with Diffusion Models
+
+## Overview
+
+DiffDock is a diffusion-based deep learning tool for molecular docking that predicts 3D binding poses of small molecule ligands to protein targets. It represents the state-of-the-art in computational docking, crucial for structure-based drug discovery and chemical biology.
+
+**Core Capabilities:**
+- Predict ligand binding poses with high accuracy using deep learning
+- Support protein structures (PDB files) or sequences (via ESMFold)
+- Process single complexes or batch virtual screening campaigns
+- Generate confidence scores to assess prediction reliability
+- Handle diverse ligand inputs (SMILES, SDF, MOL2)
+
+**Key Distinction:** DiffDock predicts **binding poses** (3D structure) and **confidence** (prediction certainty), NOT binding affinity (ΔG, Kd). Always combine with scoring functions (GNINA, MM/GBSA) for affinity assessment.
+
+## When to Use This Skill
+
+This skill should be used when:
+
+- "Dock this ligand to a protein" or "predict binding pose"
+- "Run molecular docking" or "perform protein-ligand docking"
+- "Virtual screening" or "screen compound library"
+- "Where does this molecule bind?" or "predict binding site"
+- Structure-based drug design or lead optimization tasks
+- Tasks involving PDB files + SMILES strings or ligand structures
+- Batch docking of multiple protein-ligand pairs
+
+## Installation and Environment Setup
+
+### Check Environment Status
+
+Before proceeding with DiffDock tasks, verify the environment setup:
+
+```bash
+# Use the provided setup checker
+python scripts/setup_check.py
+```
+
+This script validates Python version, PyTorch with CUDA, PyTorch Geometric, RDKit, ESM, and other dependencies.
+
+### Installation Options
+
+**Option 1: Conda (Recommended)**
+```bash
+git clone https://github.com/gcorso/DiffDock.git
+cd DiffDock
+conda env create --file environment.yml
+conda activate diffdock
+```
+
+**Option 2: Docker**
+```bash
+docker pull rbgcsail/diffdock
+docker run -it --gpus all --entrypoint /bin/bash rbgcsail/diffdock
+micromamba activate diffdock
+```
+
+**Important Notes:**
+- GPU strongly recommended (10-100x speedup vs CPU)
+- First run pre-computes SO(2)/SO(3) lookup tables (~2-5 minutes)
+- Model checkpoints (~500MB) download automatically if not present
+
+## Core Workflows
+
+### Workflow 1: Single Protein-Ligand Docking
+
+**Use Case:** Dock one ligand to one protein target
+
+**Input Requirements:**
+- Protein: PDB file OR amino acid sequence
+- Ligand: SMILES string OR structure file (SDF/MOL2)
+
+**Command:**
+```bash
+python -m inference \
+  --config default_inference_args.yaml \
+  --protein_path protein.pdb \
+  --ligand "CC(=O)Oc1ccccc1C(=O)O" \
+  --out_dir results/single_docking/
+```
+
+**Alternative (protein sequence):**
+```bash
+python -m inference \
+  --config default_inference_args.yaml \
+  --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
+  --ligand ligand.sdf \
+  --out_dir results/sequence_docking/
+```
+
+**Output Structure:**
+```
+results/single_docking/
+├── rank_1.sdf          # Top-ranked pose
+├── rank_2.sdf          # Second-ranked pose
+├── ...
+├── rank_10.sdf         # 10th pose (default: 10 samples)
+└── confidence_scores.txt
+```
+
+### Workflow 2: Batch Processing Multiple Complexes
+
+**Use Case:** Dock multiple ligands to proteins, virtual screening campaigns
+
+**Step 1: Prepare Batch CSV**
+
+Use the provided script to create or validate batch input:
+
+```bash
+# Create template
+python scripts/prepare_batch_csv.py --create --output batch_input.csv
+
+# Validate existing CSV
+python scripts/prepare_batch_csv.py my_input.csv --validate
+```
+
+**CSV Format:**
+```csv
+complex_name,protein_path,ligand_description,protein_sequence
+complex1,protein1.pdb,CC(=O)Oc1ccccc1C(=O)O,
+complex2,,COc1ccc(C#N)cc1,MSKGEELFT...
+complex3,protein3.pdb,ligand3.sdf,
+```
+
+**Required Columns:**
+- `complex_name`: Unique identifier
+- `protein_path`: PDB file path (leave empty if using sequence)
+- `ligand_description`: SMILES string or ligand file path
+- `protein_sequence`: Amino acid sequence (leave empty if using PDB)
+
+**Step 2: Run Batch Docking**
+
+```bash
+python -m inference \
+  --config default_inference_args.yaml \
+  --protein_ligand_csv batch_input.csv \
+  --out_dir results/batch/ \
+  --batch_size 10
+```
+
+**For Large Virtual Screening (>100 compounds):**
+
+Pre-compute protein embeddings for faster processing:
+```bash
+# Pre-compute embeddings
+python datasets/esm_embedding_preparation.py \
+  --protein_ligand_csv screening_input.csv \
+  --out_file protein_embeddings.pt
+
+# Run with pre-computed embeddings
+python -m inference \
+  --config default_inference_args.yaml \
+  --protein_ligand_csv screening_input.csv \
+  --esm_embeddings_path protein_embeddings.pt \
+  --out_dir results/screening/
+```
+
+### Workflow 3: Analyzing Results
+
+After docking completes, analyze confidence scores and rank predictions:
+
+```bash
+# Analyze all results
+python scripts/analyze_results.py results/batch/
+
+# Show top 5 per complex
+python scripts/analyze_results.py results/batch/ --top 5
+
+# Filter by confidence threshold
+python scripts/analyze_results.py results/batch/ --threshold 0.0
+
+# Export to CSV
+python scripts/analyze_results.py results/batch/ --export summary.csv
+
+# Show top 20 predictions across all complexes
+python scripts/analyze_results.py results/batch/ --best 20
+```
+
+The analysis script:
+- Parses confidence scores from all predictions
+- Classifies as High (>0), Moderate (-1.5 to 0), or Low (<-1.5)
+- Ranks predictions within and across complexes
+- Generates statistical summaries
+- Exports results to CSV for downstream analysis
+
+## Confidence Score Interpretation
+
+**Understanding Scores:**
+
+| Score Range | Confidence Level | Interpretation |
+|------------|------------------|----------------|
+| **> 0** | High | Strong prediction, likely accurate |
+| **-1.5 to 0** | Moderate | Reasonable prediction, validate carefully |
+| **< -1.5** | Low | Uncertain prediction, requires validation |
+
+**Critical Notes:**
+1. **Confidence ≠ Affinity**: High confidence means model certainty about structure, NOT strong binding
+2. **Context Matters**: Adjust expectations for:
+   - Large ligands (>500 Da): Lower confidence expected
+   - Multiple protein chains: May decrease confidence
+   - Novel protein families: May underperform
+3. **Multiple Samples**: Review top 3-5 predictions, look for consensus
+
+**For detailed guidance:** Read `references/confidence_and_limitations.md` using the Read tool
+
+## Parameter Customization
+
+### Using Custom Configuration
+
+Create custom configuration for specific use cases:
+
+```bash
+# Copy template
+cp assets/custom_inference_config.yaml my_config.yaml
+
+# Edit parameters (see template for presets)
+# Then run with custom config
+python -m inference \
+  --config my_config.yaml \
+  --protein_ligand_csv input.csv \
+  --out_dir results/
+```
+
+### Key Parameters to Adjust
+
+**Sampling Density:**
+- `samples_per_complex: 10` → Increase to 20-40 for difficult cases
+- More samples = better coverage but longer runtime
+
+**Inference Steps:**
+- `inference_steps: 20` → Increase to 25-30 for higher accuracy
+- More steps = potentially better quality but slower
+
+**Temperature Parameters (control diversity):**
+- `temp_sampling_tor: 7.04` → Increase for flexible ligands (8-10)
+- `temp_sampling_tor: 7.04` → Decrease for rigid ligands (5-6)
+- Higher temperature = more diverse poses
+
+**Presets Available in Template:**
+1. High Accuracy: More samples + steps, lower temperature
+2. Fast Screening: Fewer samples, faster
+3. Flexible Ligands: Increased torsion temperature
+4. Rigid Ligands: Decreased torsion temperature
+
+**For complete parameter reference:** Read `references/parameters_reference.md` using the Read tool
+
+## Advanced Techniques
+
+### Ensemble Docking (Protein Flexibility)
+
+For proteins with known flexibility, dock to multiple conformations:
+
+```python
+# Create ensemble CSV
+import pandas as pd
+
+conformations = ["conf1.pdb", "conf2.pdb", "conf3.pdb"]
+ligand = "CC(=O)Oc1ccccc1C(=O)O"
+
+data = {
+    "complex_name": [f"ensemble_{i}" for i in range(len(conformations))],
+    "protein_path": conformations,
+    "ligand_description": [ligand] * len(conformations),
+    "protein_sequence": [""] * len(conformations)
+}
+
+pd.DataFrame(data).to_csv("ensemble_input.csv", index=False)
+```
+
+Run docking with increased sampling:
+```bash
+python -m inference \
+  --config default_inference_args.yaml \
+  --protein_ligand_csv ensemble_input.csv \
+  --samples_per_complex 20 \
+  --out_dir results/ensemble/
+```
+
+### Integration with Scoring Functions
+
+DiffDock generates poses; combine with other tools for affinity:
+
+**GNINA (Fast neural network scoring):**
+```bash
+for pose in results/*.sdf; do
+    gnina -r protein.pdb -l "$pose" --score_only
+done
+```
+
+**MM/GBSA (More accurate, slower):**
+Use AmberTools MMPBSA.py or gmx_MMPBSA after energy minimization
+
+**Free Energy Calculations (Most accurate):**
+Use OpenMM + OpenFE or GROMACS for FEP/TI calculations
+
+**Recommended Workflow:**
+1. DiffDock → Generate poses with confidence scores
+2. Visual inspection → Check structural plausibility
+3. GNINA or MM/GBSA → Rescore and rank by affinity
+4. Experimental validation → Biochemical assays
+
+## Limitations and Scope
+
+**DiffDock IS Designed For:**
+- Small molecule ligands (typically 100-1000 Da)
+- Drug-like organic compounds
+- Small peptides (<20 residues)
+- Single or multi-chain proteins
+
+**DiffDock IS NOT Designed For:**
+- Large biomolecules (protein-protein docking) → Use DiffDock-PP or AlphaFold-Multimer
+- Large peptides (>20 residues) → Use alternative methods
+- Covalent docking → Use specialized covalent docking tools
+- Binding affinity prediction → Combine with scoring functions
+- Membrane proteins → Not specifically trained, use with caution
+
+**For complete limitations:** Read `references/confidence_and_limitations.md` using the Read tool
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Low confidence scores across all predictions**
+- Cause: Large/unusual ligands, unclear binding site, protein flexibility
+- Solution: Increase `samples_per_complex` (20-40), try ensemble docking, validate protein structure
+
+**Issue: Out of memory errors**
+- Cause: GPU memory insufficient for batch size
+- Solution: Reduce `--batch_size 2` or process fewer complexes at once
+
+**Issue: Slow performance**
+- Cause: Running on CPU instead of GPU
+- Solution: Verify CUDA with `python -c "import torch; print(torch.cuda.is_available())"`, use GPU
+
+**Issue: Unrealistic binding poses**
+- Cause: Poor protein preparation, ligand too large, wrong binding site
+- Solution: Check protein for missing residues, remove far waters, consider specifying binding site
+
+**Issue: "Module not found" errors**
+- Cause: Missing dependencies or wrong environment
+- Solution: Run `python scripts/setup_check.py` to diagnose
+
+### Performance Optimization
+
+**For Best Results:**
+1. Use GPU (essential for practical use)
+2. Pre-compute ESM embeddings for repeated protein use
+3. Batch process multiple complexes together
+4. Start with default parameters, then tune if needed
+5. Validate protein structures (resolve missing residues)
+6. Use canonical SMILES for ligands
+
+## Graphical User Interface
+
+For interactive use, launch the web interface:
+
+```bash
+python app/main.py
+# Navigate to http://localhost:7860
+```
+
+Or use the online demo without installation:
+- https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
+
+## Resources
+
+### Helper Scripts (`scripts/`)
+
+**`prepare_batch_csv.py`**: Create and validate batch input CSV files
+- Create templates with example entries
+- Validate file paths and SMILES strings
+- Check for required columns and format issues
+
+**`analyze_results.py`**: Analyze confidence scores and rank predictions
+- Parse results from single or batch runs
+- Generate statistical summaries
+- Export to CSV for downstream analysis
+- Identify top predictions across complexes
+
+**`setup_check.py`**: Verify DiffDock environment setup
+- Check Python version and dependencies
+- Verify PyTorch and CUDA availability
+- Test RDKit and PyTorch Geometric installation
+- Provide installation instructions if needed
+
+### Reference Documentation (`references/`)
+
+**`parameters_reference.md`**: Complete parameter documentation
+- All command-line options and configuration parameters
+- Default values and acceptable ranges
+- Temperature parameters for controlling diversity
+- Model checkpoint locations and version flags
+
+Read this file when users need:
+- Detailed parameter explanations
+- Fine-tuning guidance for specific systems
+- Alternative sampling strategies
+
+**`confidence_and_limitations.md`**: Confidence score interpretation and tool limitations
+- Detailed confidence score interpretation
+- When to trust predictions
+- Scope and limitations of DiffDock
+- Integration with complementary tools
+- Troubleshooting prediction quality
+
+Read this file when users need:
+- Help interpreting confidence scores
+- Understanding when NOT to use DiffDock
+- Guidance on combining with other tools
+- Validation strategies
+
+**`workflows_examples.md`**: Comprehensive workflow examples
+- Detailed installation instructions
+- Step-by-step examples for all workflows
+- Advanced integration patterns
+- Troubleshooting common issues
+- Best practices and optimization tips
+
+Read this file when users need:
+- Complete workflow examples with code
+- Integration with GNINA, OpenMM, or other tools
+- Virtual screening workflows
+- Ensemble docking procedures
+
+### Assets (`assets/`)
+
+**`batch_template.csv`**: Template for batch processing
+- Pre-formatted CSV with required columns
+- Example entries showing different input types
+- Ready to customize with actual data
+
+**`custom_inference_config.yaml`**: Configuration template
+- Annotated YAML with all parameters
+- Four preset configurations for common use cases
+- Detailed comments explaining each parameter
+- Ready to customize and use
+
+## Best Practices
+
+1. **Always verify environment** with `setup_check.py` before starting large jobs
+2. **Validate batch CSVs** with `prepare_batch_csv.py` to catch errors early
+3. **Start with defaults** then tune parameters based on system-specific needs
+4. **Generate multiple samples** (10-40) for robust predictions
+5. **Visual inspection** of top poses before downstream analysis
+6. **Combine with scoring** functions for affinity assessment
+7. **Use confidence scores** for initial ranking, not final decisions
+8. **Pre-compute embeddings** for virtual screening campaigns
+9. **Document parameters** used for reproducibility
+10. **Validate results** experimentally when possible
+
+## Citations
+
+When using DiffDock, cite the appropriate papers:
+
+**DiffDock-L (current default model):**
+```
+Stärk et al. (2024) "DiffDock-L: Improving Molecular Docking with Diffusion Models"
+arXiv:2402.18396
+```
+
+**Original DiffDock:**
+```
+Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
+ICLR 2023, arXiv:2210.01776
+```
+
+## Additional Resources
+
+- **GitHub Repository**: https://github.com/gcorso/DiffDock
+- **Online Demo**: https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
+- **DiffDock-L Paper**: https://arxiv.org/abs/2402.18396
+- **Original Paper**: https://arxiv.org/abs/2210.01776
+

package/skills/diffdock/assets/batch_template.csv

@@ -0,0 +1,4 @@
+complex_name,protein_path,ligand_description,protein_sequence
+example_1,protein1.pdb,CC(=O)Oc1ccccc1C(=O)O,
+example_2,,COc1ccc(C#N)cc1,MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTFSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVYIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK
+example_3,protein3.pdb,ligand3.sdf,

package/skills/diffdock/assets/custom_inference_config.yaml

@@ -0,0 +1,90 @@
+# DiffDock Custom Inference Configuration Template
+# Copy and modify this file to customize inference parameters
+
+# Model paths (usually don't need to change these)
+model_dir: ./workdir/v1.1/score_model
+confidence_model_dir: ./workdir/v1.1/confidence_model
+ckpt: best_ema_inference_epoch_model.pt
+confidence_ckpt: best_model_epoch75.pt
+
+# Model version flags
+old_score_model: false  # Set to true to use original DiffDock instead of DiffDock-L
+old_filtering_model: true
+
+# Inference steps
+inference_steps: 20  # Increase for potentially better accuracy (e.g., 25-30)
+actual_steps: 19
+no_final_step_noise: true
+
+# Sampling parameters
+samples_per_complex: 10  # Increase for difficult cases (e.g., 20-40)
+sigma_schedule: expbeta
+initial_noise_std_proportion: 1.46
+
+# Temperature controls - Adjust these to balance exploration vs accuracy
+# Higher values = more diverse predictions, lower values = more focused predictions
+
+# Sampling temperatures
+temp_sampling_tr: 1.17   # Translation sampling temperature
+temp_sampling_rot: 2.06  # Rotation sampling temperature
+temp_sampling_tor: 7.04  # Torsion sampling temperature (increase for flexible ligands)
+
+# Psi angle temperatures
+temp_psi_tr: 0.73
+temp_psi_rot: 0.90
+temp_psi_tor: 0.59
+
+# Sigma data temperatures
+temp_sigma_data_tr: 0.93
+temp_sigma_data_rot: 0.75
+temp_sigma_data_tor: 0.69
+
+# Feature flags
+no_model: false
+no_random: false
+ode: false  # Set to true to use ODE solver instead of SDE
+different_schedules: false
+limit_failures: 5
+
+# Output settings
+# save_visualisation: true  # Uncomment to save SDF files
+
+# ============================================================================
+# Configuration Presets for Common Use Cases
+# ============================================================================
+
+# PRESET 1: High Accuracy (slower, more thorough)
+# samples_per_complex: 30
+# inference_steps: 25
+# temp_sampling_tr: 1.0
+# temp_sampling_rot: 1.8
+# temp_sampling_tor: 6.5
+
+# PRESET 2: Fast Screening (faster, less thorough)
+# samples_per_complex: 5
+# inference_steps: 15
+# temp_sampling_tr: 1.3
+# temp_sampling_rot: 2.2
+# temp_sampling_tor: 7.5
+
+# PRESET 3: Flexible Ligands (more conformational diversity)
+# samples_per_complex: 20
+# inference_steps: 20
+# temp_sampling_tr: 1.2
+# temp_sampling_rot: 2.1
+# temp_sampling_tor: 8.5  # Increased torsion temperature
+
+# PRESET 4: Rigid Ligands (more focused predictions)
+# samples_per_complex: 10
+# inference_steps: 20
+# temp_sampling_tr: 1.1
+# temp_sampling_rot: 2.0
+# temp_sampling_tor: 6.0  # Decreased torsion temperature
+
+# ============================================================================
+# Usage Example
+# ============================================================================
+# python -m inference \
+#   --config custom_inference_config.yaml \
+#   --protein_ligand_csv input.csv \
+#   --out_dir results/