@pikaa-ai/pikaa 0.3.23 → 0.3.25

package/skills/get-available-resources/SKILL.md

@@ -1,260 +0,0 @@
----
-name: get-available-resources
-description: Detect host inventory and effective CPU, memory, disk, scheduler, container, and accelerator limits when a user asks for resource-aware planning or before a clearly resource-sensitive local workload. Produces a redacted JSON snapshot and conservative planning helpers without stress tests or assuming visible host hardware is usable.
-license: MIT
-compatibility: Python 3.11+ on Linux, macOS, or Windows; standard library by default, optional psutil 7.2.2; accelerator and scheduler CLIs are optional read-only probes.
-metadata:
-  version: "1.2"
-  skill-author: K-Dense Inc.
----
-
-# Get Available Resources
-
-Build a conservative picture of resources available to the **current process**.
-Keep host inventory, process affinity, cgroup/container limits, scheduler
-allocation, and accelerator runtime usability separate.
-
-## Safety contract
-
-Follow these rules:
-
-- Run detection when the user requests it or a specific workload needs resource
-  planning. Do not persist a fingerprint for every scientific task.
-- Use stdout by default. Persist only when the user chooses an explicit generic
-  local filename.
-- Do not run stress tests, benchmarks, large allocations, write probes, device
-  resets, driver installation, or clock/power changes.
-- Do not dump the environment. Read only the named Slurm and accelerator
-  variables implemented by the detector.
-- Do not report hostnames, absolute paths, cgroup paths, job IDs, device UUIDs,
-  PCI addresses, or raw visibility-variable values.
-- Treat a missing observation as unknown. Never convert unknown to unlimited.
-- Never infer that a visible host CPU, memory pool, or GPU is usable inside a
-  scheduler allocation or container.
-
-The bundled detector uses only fixed executable/argument tuples, no shell,
-short timeouts, bounded stdout/stderr, and partial-failure warnings.
-
-## Quick start
-
-Run from this skill directory.
-
-### Ephemeral stdout snapshot
-
-```bash
-python scripts/detect_resources.py
-```
-
-The command emits only JSON to stdout. Redirect it only when ordinary shell
-permissions are acceptable.
-
-### Explicit private file
-
-```bash
-python scripts/detect_resources.py --output resource-snapshot.json
-```
-
-Explicit output is restricted to one `.json` filename in the current
-directory, uses private permissions, rejects symlinks and path traversal, and
-refuses overwrite unless `--force` is supplied.
-
-### Optional psutil enhancement
-
-The standard-library detector works without installation. For broader
-cross-platform physical-core, affinity, available-memory, swap, and disk
-coverage:
-
-```bash
-uv pip install "psutil==7.2.2"
-```
-
-The import is lazy. Failure to import psutil becomes a warning, not a fatal
-error.
-
-### Skip management-tool probes
-
-```bash
-python scripts/detect_resources.py --skip-accelerators
-```
-
-Use this when accelerator discovery latency is undesirable. The detector still
-summarizes the presence and state of allowlisted visibility variables without
-returning their values.
-
-## Required interpretation
-
-### CPU
-
-Read these as different facts:
-
-- `cpu.host.logical`: system-visible scheduling units.
-- `cpu.host.physical`: physical topology, or null; never inferred from logical
-  count.
-- `cpu.process.affinity_logical`: current affinity-set size when supported.
-- `cpu.cgroup_v2.cpuset_logical`: effective cgroup cpuset size.
-- `cpu.cgroup_v2.quota_cores`: finite `cpu.max` capacity, possibly fractional.
-- `scheduler.allocation.cpu_per_process`: bounded Slurm per-task
-  interpretation when scope is clear.
-- `cpu.effective.capacity_cores`: minimum positive observed constraint.
-- `cpu.effective.worker_ceiling`: conservative floor for CPU process workers.
-
-A quota of 1.5 is CPU-time capacity, not 1.5 physical cores. Affinity and
-cpusets constrain placement; quota constrains bandwidth.
-
-### Memory
-
-Keep these separate:
-
-- host total/available memory;
-- current cgroup usage, hard `memory.max`, and remaining hierarchical capacity;
-- `memory.high`, which is a pressure/throttle boundary rather than a hard cap;
-- scheduler memory allocation and its scope; and
-- conservative effective hard limit and available estimate.
-
-On Apple silicon, `memory.model` is `unified_cpu_gpu`. Do not add integrated GPU
-memory to RAM or describe it as separate VRAM.
-
-### Accelerators
-
-Each device is a backend **candidate**:
-
-- NVIDIA GPU → CUDA candidate;
-- AMD GPU → ROCm candidate;
-- Apple integrated GPU → Metal candidate.
-
-Management-query visibility does not establish:
-
-1. scheduler/container permission;
-2. device-node access;
-3. driver/runtime compatibility;
-4. framework package compatibility; or
-5. operator/data-type support.
-
-Therefore `runtime_usable_devices` remains null and each device says
-`runtime_compatibility: not_tested`. Visibility/allocation counts are upper
-bounds, not guarantees.
-
-### Disk
-
-`capacity_bytes`, filesystem `free_bytes`, user-available blocks, and a
-non-writing permission check are distinct. Filesystem or project quotas can
-still be stricter. The absolute working path is always redacted.
-
-### Scheduler and container
-
-Slurm variables describe allocation scope, but enforcement depends on site
-configuration such as task affinity or cgroups. Prefer affinity and cgroup
-observations as enforcement evidence.
-
-Container markers identify context; cgroup controls identify limits. A
-container with no finite cgroup value can still see host inventory, and a
-non-root cgroup is not automatically labeled a container.
-
-See [`references/resource_semantics.md`](references/resource_semantics.md) for
-the detailed platform rules.
-
-## Plan a workload
-
-The planner consumes a validated snapshot and performs no work:
-
-```bash
-python scripts/plan_workload.py resource-snapshot.json \
-  --workload cpu \
-  --tasks 100 \
-  --memory-per-worker-mib 2048
-```
-
-Optional controls:
-
-- `--workers N`: explicit upper bound.
-- `--reserve-memory-mib N`: memory kept outside the worker budget.
-- `--workload cpu|mixed|io`: selects a bounded worker heuristic.
-- `--accelerator none|any|cuda|rocm|metal`: requests a candidate backend
-  decision without claiming usability.
-- `--output plan.json`: explicit private local output; stdout is default.
-
-For CPU or mixed work, use `suggested_workers` and
-`threads_per_worker` together. Process workers multiplied by BLAS/OpenMP native
-threads can oversubscribe an allocation.
-
-The I/O plan permits bounded oversubscription (maximum 32) but labels it a
-heuristic. Benchmark only the real representative workload and stay within
-scheduler/container limits.
-
-## Validate or diff snapshots
-
-Validate:
-
-```bash
-python scripts/snapshot_tools.py validate resource-snapshot.json
-```
-
-Diff resource state while ignoring `observed_at`:
-
-```bash
-python scripts/snapshot_tools.py diff before.json after.json
-```
-
-Use `--include-volatile` to include the timestamp. Inputs must be regular,
-non-symlink JSON files no larger than 1 MiB. Diffs are bounded.
-
-The schema and null/zero meanings are documented in
-[`references/snapshot_schema.md`](references/snapshot_schema.md).
-
-## Optional accelerator diagnostic plan
-
-Generate a plan without executing any diagnostic:
-
-```bash
-python scripts/accelerator_diagnostics.py resource-snapshot.json \
-  --backend auto
-```
-
-The result contains fixed, read-only management query argument lists and
-separate gates for visibility, permission, and runtime compatibility. Run a
-framework's official availability check only in the exact environment that
-will execute the workload. Do not install or mutate drivers automatically.
-
-## Partial failures and provenance
-
-One failed probe must not erase successful observations. Inspect:
-
-- `completeness`;
-- sorted `warnings` with stable codes;
-- sorted `provenance` source/status records; and
-- null fields.
-
-Subprocess stderr and raw exception text are not copied into the snapshot
-because they can contain identifiers or paths.
-
-## Platform notes
-
-- **Linux:** reads only bounded `/proc` and cgroup v2 files. Ancestor CPU and
-  memory limits are considered.
-- **macOS:** uses fixed `sysctl` keys and a bounded
-  `system_profiler SPDisplaysDataType -json` query. Apple silicon memory is
-  unified.
-- **Windows:** optional psutil improves physical-core, affinity, available
-  memory, and swap observations. Processor-group scope can make host and
-  process counts differ.
-- **Slurm:** reads an allowlist of allocation variables. It never emits job,
-  node, submit-host, GPU-ID, or path values.
-- **NVIDIA/AMD:** management CLIs are optional. Absence is normal; timeout,
-  truncation, parse failure, and runtime uncertainty remain explicit.
-
-## Bundled files
-
-- `scripts/detect_resources.py` — redacted snapshot collector.
-- `scripts/plan_workload.py` — deterministic worker/memory planner.
-- `scripts/snapshot_tools.py` — schema validator and bounded structural diff.
-- `scripts/accelerator_diagnostics.py` — non-executing read-only diagnostic
-  plan.
-- `tests/get-available-resources/` in the repository root — network-free
-  Linux, macOS, Windows, cgroup, Slurm, and accelerator cases.
-- `references/resource_semantics.md` — interpretation and platform details.
-- `references/snapshot_schema.md` — schema 1.1 contract.
-- `references/sources.md` — dated official-source ledger.
-
-Official documentation was refreshed on **2026-07-23**; consult
-[`references/sources.md`](references/sources.md) before changing semantics or
-dependency pins.

package/skills/gget/SKILL.md

@@ -1,153 +0,0 @@
----
-name: gget
-description: "Fast CLI/Python queries to 20+ bioinformatics databases. Use for quick lookups: gene info, BLAST/BLAT, viral sequence downloads, AlphaFold structures, enrichment analysis, OpenTargets, COSMIC, CELLxGENE, and 8cube mouse specificity/expression data. Best for interactive exploration and simple queries. For batch processing or advanced BLAST use biopython; for multi-database Python workflows use bioservices."
-license: BSD-2-Clause license
-allowed-tools: Read Write Edit Bash
-compatibility: Requires Python >=3.8 and gget 0.30.5-compatible APIs. Optional setup modules may install scientific dependencies that lag the newest Python releases; use Python 3.9 or 3.10 if `gget setup cellxgene` or `gget setup alphafold` fails.
-metadata:
-  version: "1.4"
-  skill-author: K-Dense Inc.
----
-
-# gget
-
-## Overview
-
-gget is a command-line bioinformatics tool and Python package providing unified access to 20+ genomic databases and analysis methods. Query gene information, sequence analysis, protein structures, viral sequences, expression data, disease associations, and mouse tissue/cell specificity metrics through a consistent interface. Most gget modules work both as command-line tools and as Python functions.
-
-**Important**: The databases queried by gget are continuously updated, which sometimes changes their structure. Guidance here targets gget 0.30.5 (PyPI current as of 2026-06-07). For reproducible work, pin `gget==0.30.5`; for broken upstream database adapters, update gget after checking release notes.
-
-## Installation
-
-Install gget in a clean virtual environment to avoid conflicts:
-
-```bash
-# Reproducible install targeting this skill
-uv venv .venv
-source .venv/bin/activate
-uv pip install "gget==0.30.5"
-
-# In Python/Jupyter
-import gget
-```
-
-## Quick Start
-
-Basic usage pattern for all modules:
-
-```bash
-# Command-line
-gget <module> [arguments] [options]
-
-# Python
-gget.module(arguments, options)
-```
-
-Most modules return:
-- **Command-line**: JSON (default) or CSV with `-csv` flag
-- **Python**: DataFrame or dictionary
-
-Common flags across modules:
-- `-o/--out`: Save results to file
-- `-q/--quiet`: Suppress progress information
-- `-csv`: Return CSV format (command-line only)
-
-Python argument names generally match long CLI options without leading dashes. For example, `--census_version` becomes `census_version=...`. Use `gget <module> --help` for the exact current signature.
-
-## Module Categories
-
-gget exposes 23 modules in six categories. Parameters, CLI and Python examples, and
-return shapes for every one are in
-[references/module_catalog.md](references/module_catalog.md); fuller per-parameter
-documentation is in [references/module_reference.md](references/module_reference.md).
-
-| Category | Modules |
-| --- | --- |
-| 1. Reference & gene information | `ref` (Ensembl reference downloads), `search` (gene search), `info` (gene/transcript detail), `seq` (nucleotide and protein sequences) |
-| 2. Sequence analysis & alignment | `blast`, `blat`, `muscle` (multiple alignment), `diamond` (local alignment) |
-| 3. Structural & protein analysis | `pdb` (structures and metadata), `alphafold` (structure prediction), `elm` (linear motifs) |
-| 4. Expression & disease data | `archs4` (correlation, tissue expression), `cellxgene` (single-cell), `enrichr` (enrichment), `bgee` (orthology and expression), `opentargets` (disease and drug), `cbio` (cancer genomics), `cosmic` (mutations) |
-| 5. Viral & mouse specificity | `virus` (viral sequences), `8cube` (mouse specificity and expression) |
-| 6. Additional tools | `mutate` (mutated sequences), `gpt` (text generation), `setup` (install module dependencies) |
-
-Several modules need a one-time `gget setup` before first use (`alphafold`, `elm`,
-`cellxgene`), and `cosmic` prompts for COSMIC credentials to download its database.
-
-## Common Workflows
-
-Worked multi-module pipelines — gene characterization, structural comparison, expression
-and enrichment analysis, disease and drug association, orthology comparison, and
-reference-file preparation for kallisto or alignment — are in
-[references/common_workflows.md](references/common_workflows.md), with longer versions in
-[references/workflows.md](references/workflows.md).
-
-## Best Practices
-
-### Data Retrieval
-- Use `--limit` to control result sizes for large queries
-- Save results with `-o/--out` for reproducibility
-- Check database versions/releases for consistency across analyses
-- Use `--quiet` in production scripts to reduce output
-
-### Sequence Analysis
-- For BLAST/BLAT, start with default parameters, then adjust sensitivity
-- Use `gget diamond` with `--threads` for faster local alignment
-- Save DIAMOND databases with `--diamond_db` for repeated queries
-- For multiple sequence alignment, use `-s5/--super5` for large datasets
-
-### Expression and Disease Data
-- Gene symbols are case-sensitive in cellxgene (e.g., 'PAX7' vs 'Pax7')
-- Run `gget setup` before first use of alphafold, cellxgene, elm, gpt
-- For enrichment analysis, use database shortcuts for convenience
-- Cache cBioPortal data with `-dd` to avoid repeated downloads
-- For OpenTargets, inspect returned column names before writing filters; gget 0.30.5 follows the newer OpenTargets API schema
-
-### Structure Prediction
-- AlphaFold multimer predictions: use `-mr 20` for higher accuracy
-- Use `-r` flag for AMBER relaxation of final structures
-- Visualize results in Python with `plot=True`
-- Check PDB database first before running AlphaFold predictions
-
-### Viral Data
-- Use restrictive filters with `gget virus` before requesting broad viral datasets
-- Keep `command_summary.txt` with downstream results for reproducibility and recovery after partial downloads
-- Use `--baseline` and `--merge-results` to resume interrupted viral metadata/sequence downloads
-
-### Error Handling
-- Database structures change; when an adapter breaks, check upstream release notes and pin the newer fixed version explicitly
-- Pin the known-good version for reproducible environments: `uv pip install "gget==0.30.5"`
-- Process max ~1000 Ensembl IDs at once with gget info
-- For large-scale analyses, implement rate limiting for API queries
-- Use virtual environments to avoid dependency conflicts
-- Keep COSMIC and OpenAI credentials in named environment variables or interactive prompts; do not write real credentials into examples, notebooks, or logs
-
-## Output Formats
-
-### Command-line
-- Default: JSON
-- CSV: Add `-csv` flag
-- FASTA: gget seq, gget mutate
-- PDB: gget pdb, gget alphafold
-- PNG: gget cbio plot
-- FASTA/CSV/JSONL folder: gget virus
-
-### Python
-- Default: DataFrame or dictionary
-- JSON: Add `json=True` parameter
-- Save to file: Add `save=True` or specify `out="filename"`
-- AnnData: gget cellxgene
-- DataFrame/JSON: gget 8cube specificity, psi_block, expression
-
-## Resources
-
-This skill includes reference documentation for detailed module information:
-
-### references/
-- `module_reference.md` - Comprehensive parameter reference for all modules
-- `database_info.md` - Information about queried databases and their update frequencies
-- `workflows.md` - Extended workflow examples and use cases
-
-For additional help:
-- Official documentation: https://pachterlab.github.io/gget/
-- GitHub issues: https://github.com/pachterlab/gget/issues
-- Citation: Luebbert, L. & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. https://doi.org/10.1093/bioinformatics/btac836

package/skills/ginkgo-cloud-lab/SKILL.md

@@ -1,106 +0,0 @@
----
-name: ginkgo-cloud-lab
-description: Submit and manage protocols on Ginkgo Bioworks Cloud Lab (cloud.ginkgo.bio), a web-based interface for autonomous lab execution on Reconfigurable Automation Carts (RACs). Use when the user wants to run protein expression and purification (cell-free, E. coli, or Pichia), HiBiT or A280 or LabChip quantification, IVT mRNA/circRNA synthesis, thermal shift / developability assays, Echo-MS enzyme or analyte methods, SPR target onboarding, fluorescent pixel art, or otherwise interact with Ginkgo Cloud Lab services. Covers protocol selection, input preparation, pricing, and ordering workflows.
-license: MIT license
-allowed-tools: Read
-metadata:
-  version: "2.0"
----
-
-# Ginkgo Cloud Lab
-
-## Overview
-
-Ginkgo Cloud Lab (https://cloud.ginkgo.bio) provides remote access to Ginkgo Bioworks' autonomous lab infrastructure. Protocols are executed on Reconfigurable Automation Carts (RACs) -- modular units with robotic arms, maglev sample transport, and industrial-grade software spanning 70+ instruments.
-
-The platform also includes **EstiMate**, an AI agent that accepts human-language protocol descriptions and returns feasibility assessments and pricing for custom workflows beyond the listed protocols.
-
-The catalog is organized into **Expression & Purification** (in vitro / cell-free / E. coli / Pichia), **Characterization & Assay**, **Method & Target Onboarding**, and **Specialty**. Pick a protocol below, then read its reference file for inputs, outputs, the automated workflow, and ordering details.
-
-## Available Protocols
-
-### Expression & Purification - In vitro
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [IVT mRNA/circRNA Synthesis](references/ivt-rna-synthesis-qpcr.md) | qPCR (mRNA or circRNA, 384-well) | $99/sample | up to 12 business days | Certified |
-
-### Expression & Purification - Cell-free (E. coli CFPS)
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Validate sequence expression](references/cell-free-protein-expression-validation.md) | Go/no-go titer + purity (up to 1800 bp) | $39/sample | up to 10 days | Certified |
-| [Optimize expression conditions](references/cell-free-protein-expression-optimization.md) | DoE across 24 conditions | $199/sample | up to 11 days | Certified |
-| [Express + quantify (HiBiT)](references/cell-free-protein-expression-hibit.md) | Luminescence, no purification | $39/sample | up to 11 days | Certified |
-| [Express + purify (A280)](references/cfps-strep-tag-purification-a280.md) | Strep-tag, A280 yield | $149/sample | up to 11 days | Certified |
-| [Express + purify minibinder](references/minibinder-strep-tag-a280.md) | Strep-tag, A280, LabChip | $149/sample | up to 11 days | Certified |
-| [Express + purify (A280 + LabChip)](references/cfps-expression-purification-quantification.md) | Strep-tag, A280 + purity/size | $159/sample | up to 12 days | Certified |
-
-### Expression & Purification - E. coli
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Express + quantify (HiBiT)](references/ecoli-protein-expression-hibit.md) | Luminescence (up to 384 constructs) | $79/sample | up to 3 weeks | Certified |
-| [Express + purify (A280)](references/ecoli-protein-expression-histag-a280.md) | His-tag, A280 yield | $199/sample | up to 3 weeks | Certified |
-| [Express + purify minibinder](references/ecoli-minibinder-expression-histag-a280.md) | His-tag, A280 yield | $199/sample | up to 3 weeks | Certified |
-| [Express + purify (A280 + LabChip)](references/ecoli-expression-purification-quantification.md) | His-tag, A280 + purity/size | $209/sample | up to 3 weeks | Certified |
-
-### Expression & Purification - Pichia
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Express + quantify (LabChip)](references/pichia-protein-expression-labchip.md) | Secreted protein, size/purity (up to 96) | $89/sample | up to 4 weeks | Certified (New) |
-
-### Characterization & Assay
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Express + thermal shift](references/cfps-strep-purification-thermal-shift.md) | SYPRO Orange Tm (Tonset, TM1-3) | $159/sample | up to 12 days | Certified |
-| [Detect enzymatic products (Echo-MS)](references/echo-ms-cfps-detection.md) | Substrate/product by Echo-MS | $44/sample | up to 13 days | Beta |
-
-### Method & Target Onboarding
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Onboard Echo-MS method](references/echo-ms-method-onboarding.md) | Calibration curve, LOD/LOQ | $799/molecule | up to 3 weeks | Certified |
-| [Onboard SPR target](references/spr-target-onboarding.md) | Validated SPR capture method | $1,399/target | up to 4 weeks | Beta |
-
-### Specialty
-
-| Protocol | Readout | Price | Turnaround | Status |
-|---|---|---|---|---|
-| [Generate fluorescent pixel art](references/fluorescent-pixel-art-generation.md) | UV photo, 7-color E. coli palette | $25/plate | up to 7 days | Beta |
-
-**Coming soon:** Protein Expression and Binding Affinity Characterization (express + purify, then screen binding affinity against a target).
-
-## Choosing a Protocol
-
-- **Quick expressibility screen?** Cell-free HiBiT ($39) or Validate sequence expression ($39).
-- **Need purified protein + yield?** A280 tiers (cell-free or E. coli); add LabChip for purity/size.
-- **Difficult / membrane / disulfide / cofactor targets?** Cell-free Optimize (24-condition DoE).
-- **Secreted or eukaryotic targets?** Pichia expression.
-- **Screening de novo binders/minibinders?** Cell-free or E. coli minibinder tiers, then SPR onboarding for kinetics.
-- **Enzyme activity / biocatalysis?** Echo-MS enzymatic detection (onboard the analyte method first).
-- **Stability / developability ranking?** Thermal shift assay.
-- **RNA (mRNA/circRNA)?** IVT synthesis + qPCR.
-
-## General Ordering Workflow
-
-1. Select a protocol at https://cloud.ginkgo.bio/protocols
-2. Configure parameters (number of proteins/samples/molecules/targets, replicates, plates)
-3. Download the protocol's input template and upload inputs (FASTA/CSV/XLSX for sequence protocols; Design Tool for pixel art; vendor catalog numbers for onboarding)
-4. Add any special requirements in the Additional Details field
-5. Provide an email, agree to the protocol terms, and add to cart / submit to receive a feasibility report and price quote
-
-For protocols not listed above, use the **EstiMate** chat (https://cloud.ginkgo.bio/estimate) to describe a custom protocol in plain language and receive a compatibility assessment and pricing.
-
-## Authentication
-
-Access Ginkgo Cloud Lab at https://cloud.ginkgo.bio. Account creation or institutional access may be required. Contact Ginkgo at cloud@ginkgo.bio for access questions.
-
-## Key Infrastructure
-
-- **RACs (Reconfigurable Automation Carts):** Modular robotic units with high-precision arms and maglev transport
-- **Catalyst Software:** Protocol orchestration, scheduling, parameterization, and real-time monitoring
-- **70+ integrated instruments:** Agilent Bravo liquid handlers, Beckman/Labcyte Echo acoustic dispensers, BMG PHERAstar / Tecan Spark readers, Revvity LabChip, Bio-Rad CFX Opus, Nicoya Alto SPR, SciEx Echo-MS, Inheco/Cytomat incubators, and more
-- **Nebula:** Ginkgo's autonomous lab facility in Boston, MA