@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/ontology-term-resolution/SKILL.md

@@ -1,147 +0,0 @@
----
-name: ontology-term-resolution
-description: Resolve free-text scientific labels to ontology term IDs and validate existing CURIEs against the EBI Ontology Lookup Service (OLS4). Use whenever an ontology identifier must be produced or checked - annotating tissue, cell type, disease, phenotype, assay, chemical, organism, sex, or developmental stage fields; preparing metadata for GEO, ENA, BioSamples, CELLxGENE, HCA, or ISA-Tab submission; auditing a metadata table of term IDs; checking whether a term is obsolete and what replaced it; or mapping between ontologies. Triggers include "ontology term", "ontology ID", "CURIE", "controlled vocabulary", "UBERON", "CL:", "MONDO", "HPO", "EFO", "ChEBI", "NCBITaxon", "GO term", "PATO", "annotate this tissue/cell type/disease", and any request to emit or verify an identifier shaped like PREFIX:0001234.
-license: MIT
-compatibility: Requires Python 3.11+. Scripts use only the standard library - no third-party packages. Needs network access to https://www.ebi.ac.uk/ols4 (public, no API key).
-allowed-tools: Read Write Edit Bash
-metadata:
-  version: "1.0"
-  skill-author: K-Dense Inc.
----
-
-# Ontology Term Resolution
-
-## When to use
-
-Any time an ontology identifier is about to be written down or trusted: annotating a metadata
-column, filling a submission template, auditing a table someone else produced, or checking whether
-an ID in an old file is still current.
-
-## The rule
-
-**Never write an ontology ID from memory, and never accept one without checking it.**
-
-Ontology IDs are memorable in form and arbitrary in detail. A plausible-looking `UBERON:0002108`
-is a real term (small intestine) that is not the liver, and nothing downstream will catch the
-substitution — the ID is well-formed, the ontology is right, and the metadata is silently wrong.
-Reviewers cannot spot it either, which is why these errors persist into published datasets.
-
-Every ID this skill emits comes from a live OLS lookup. Every ID it is handed gets verified.
-
-## Two directions
-
-| Direction | Script | Question answered |
-| --- | --- | --- |
-| text → ID | `scripts/resolve_terms.py` | What is the term for "left ventricle"? |
-| ID → verdict | `scripts/validate_terms.py` | Is `EFO:0001067` real, current, and labelled what this file claims? |
-
-Both take single values or files, emit TSV or JSON, and need no packages beyond the standard
-library.
-
-## Resolve text to terms
-
-```bash
-cd skills/ontology-term-resolution/scripts
-
-# one string, constrained to the ontology that should define it
-python3 resolve_terms.py "liver" --ontology uberon
-```
-
-```
-query   rank  curie           label  ontology  match_type   strategy  defining_ontology
-liver   1     UBERON:0002107  liver  uberon    exact_label  exact     true
-```
-
-```bash
-# a column of tissue names; anything not an exact hit is reported, not guessed
-python3 resolve_terms.py --input tissues.txt --ontology uberon \
-    --exact-only --format tsv -o resolved.tsv
-
-# accept fuzzy fallbacks, then review the partial hits by hand
-python3 resolve_terms.py "left ventrical of heart" --ontology uberon --top 3
-```
-
-The search escalates `exact` (label and synonym) → `token` → `fulltext` and stops at the first
-strategy that returns anything, reporting which one fired. `--exact-only` disables the ladder.
-`--branch UBERON:0000465` restricts candidates to descendants of a term.
-
-**Read `match_type` before using a result.** `exact_label` and `exact_synonym` are safe;
-`partial` means OLS returned its best guess for a string that does not exist as written, and
-needs a human decision. `unresolved` is a legitimate output — see `references/curation-rules.md`
-for the normalisations worth retrying first.
-
-## Validate existing IDs
-
-```bash
-python3 validate_terms.py UBERON:0002107 EFO:0001067 UBERON:9999999
-```
-
-```
-id              status     actual_label                  ontology  replacement     detail
-UBERON:0002107  ok         liver                         uberon
-EFO:0001067     obsolete   obsolete_parasitic infection  efo       MONDO:0005135   obsolete; replaced by MONDO:0005135
-UBERON:9999999  not_found                                                          no such term in the ontology this prefix names
-```
-
-Exit code is 1 if anything failed, 0 otherwise, 2 on usage or network trouble — so it works as a
-CI gate on a metadata file:
-
-```bash
-# id + label columns; catches IDs that exist but are labelled as something else
-python3 validate_terms.py --input metadata.tsv --strict
-
-# a tissue column must hold UBERON anatomical entities and nothing else
-python3 validate_terms.py --input tissue_ids.tsv \
-    --branch UBERON:0000465 --expect-ontology uberon
-```
-
-| Status | Meaning | Verdict |
-| --- | --- | --- |
-| `ok` | Exists, current, consistent with everything asserted | pass |
-| `matched_synonym` | Claimed label is a synonym; primary label differs | warn |
-| `imported_only` | Home ontology no longer asserts this ID | warn |
-| `not_a_class` | Term is a property or individual | warn |
-| `not_found` | No such term | fail |
-| `obsolete` | Obsoleted; `replacement` gives the successor when one exists | fail |
-| `label_mismatch` | ID and claimed label describe different things | fail |
-| `wrong_ontology` | Right kind of ID, wrong ontology for this column | fail |
-| `wrong_branch` | Not a descendant of the required root | fail |
-| `malformed_curie` | Not of the form `PREFIX:local` | fail |
-
-`--strict` promotes warnings to failures.
-
-## API behaviour that will mislead you
-
-These are verified against the live service and are the reason this skill ships scripts rather
-than a recipe. Full detail in `references/ols4-api.md`.
-
-| Trap | Consequence |
-| --- | --- |
-| `exact=true` is exact **token** matching | `liver` returns 161 hits in UBERON; adding `queryFields=label` returns 1 |
-| `/search` never returns `is_obsolete` or `term_replaced_by` | Named in `fieldList` they are dropped silently; only term detail can answer "is this ID still current" |
-| `ontology=efo` returns MONDO and CL hits | Ontologies import each other; filter on the CURIE prefix yourself |
-| The same term appears once per importing ontology | Deduplicate on `obo_id`, keep `is_defining_ontology: true` |
-| The `obo_id` index has holes | `MONDO:0000001` is live but unindexed by `obo_id`; an IRI fallback is required to avoid a false `not_found` |
-| IRIs are not all OBO PURLs | EFO and Orphanet use their own namespaces — resolve IRIs, do not template them |
-| OxO is retired | Returns HTML with HTTP 200; use term cross-references or SSSOM instead |
-| A branch check does not exclude cell types from anatomy | CARO puts `cell` under `anatomical structure`; constrain the prefix too |
-
-## Choosing the ontology
-
-MONDO for disease, HP for phenotype, UBERON for tissue, CL for cell type, EFO for assay, ChEBI for
-compounds, NCBITaxon for organism, PATO for sex and for `normal`. Prefix-to-OLS-id mappings (`HP`
-is served as `hp`, `Orphanet` as `ordo`), branch roots for `--branch`, and the overlapping-ontology
-judgement calls are in `references/ontology-registry.md`.
-
-## Reporting results
-
-Give the ID **and** the label, and say how each was matched. A table of bare IDs cannot be
-reviewed. State unresolved terms explicitly rather than filling them with the nearest hit.
-
-## References
-
-- `references/ols4-api.md` — endpoints, parameters, response fields, and every verified trap.
-- `references/ontology-registry.md` — prefix/ontology-id table, branch roots, which ontology owns
-  which concept.
-- `references/curation-rules.md` — candidate-selection procedure, normalisations to retry,
-  auditing an existing table, obsolete terms, cross-ontology mapping.

package/skills/open-notebook/SKILL.md

@@ -1,297 +0,0 @@
----
-name: open-notebook
-description: Self-hosted, open-source alternative to Google NotebookLM for AI-powered research and document analysis. Use when organizing research materials into notebooks, ingesting diverse content sources (PDFs, videos, audio, web pages, Office documents), generating AI-powered notes and summaries, creating multi-speaker podcasts from research, chatting with documents using context-aware AI, searching across materials with full-text and vector search, or running custom content transformations. Supports 16+ AI providers including OpenAI, Anthropic, Google, Ollama, Groq, and Mistral with complete data privacy through self-hosting.
-license: MIT
-metadata:
-  version: "1.2"
-  skill-author: K-Dense Inc.
-  openclaw:
-    envVars:
-    - name: OPEN_NOTEBOOK_URL
-      required: true
-      description: Open Notebook server URL.
-    - name: OPEN_NOTEBOOK_PASSWORD
-      required: false
-      description: Open Notebook password, if auth is enabled.
-    - name: OPEN_NOTEBOOK_ENCRYPTION_KEY
-      required: false
-      description: Encryption key for stored content, if configured.
----
-
-# Open Notebook
-
-## Overview
-
-Open Notebook is an open-source, self-hosted alternative to Google's NotebookLM that enables researchers to organize materials, generate AI-powered insights, create podcasts, and have context-aware conversations with their documents — all while maintaining complete data privacy.
-
-Unlike Google's Notebook LM, which has no publicly available API outside of the Enterprise version, Open Notebook provides a comprehensive REST API, supports 16+ AI providers, and runs entirely on your own infrastructure.
-
-**Key advantages over NotebookLM:**
-- Full REST API for programmatic access and automation
-- Choice of 16+ AI providers (not locked to Google models)
-- Multi-speaker podcast generation with 1-4 customizable speakers (vs. 2-speaker limit)
-- Complete data sovereignty through self-hosting
-- Open source and fully extensible (MIT license)
-
-**Repository:** https://github.com/lfnovo/open-notebook
-
-## Quick Start
-
-### Prerequisites
-
-- Docker Desktop installed
-- API key for at least one AI provider (or local Ollama for free local inference)
-
-### Installation
-
-Deploy Open Notebook using Docker Compose:
-
-```bash
-# Download the docker-compose file
-curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml
-
-# Set the required encryption key
-export OPEN_NOTEBOOK_ENCRYPTION_KEY="your-secret-key-here"
-
-# Launch the services
-docker-compose up -d
-```
-
-Access the application:
-- **Frontend UI:** http://localhost:8502
-- **REST API:** http://localhost:5055
-- **API Documentation:** http://localhost:5055/docs
-
-### Configure AI Provider
-
-After startup, configure at least one AI provider:
-
-1. Navigate to **Settings > API Keys** in the UI
-2. Add credentials for your preferred provider (OpenAI, Anthropic, etc.)
-3. Test the connection and discover available models
-4. Register models for use across the platform
-
-Or configure via the REST API:
-
-```python
-import requests
-
-BASE_URL = "http://localhost:5055/api"
-
-# Add a credential for an AI provider
-response = requests.post(f"{BASE_URL}/credentials", json={
-    "provider": "openai",
-    "name": "My OpenAI Key",
-    "api_key": "sk-..."
-})
-credential = response.json()
-
-# Discover available models
-response = requests.post(
-    f"{BASE_URL}/credentials/{credential['id']}/discover"
-)
-discovered = response.json()
-
-# Register discovered models
-requests.post(
-    f"{BASE_URL}/credentials/{credential['id']}/register-models",
-    json={"model_ids": [m["id"] for m in discovered["models"]]}
-)
-```
-
-## Core Features
-
-### Notebooks
-Organize research into separate notebooks, each containing sources, notes, and chat sessions.
-
-```python
-import requests
-
-BASE_URL = "http://localhost:5055/api"
-
-# Create a notebook
-response = requests.post(f"{BASE_URL}/notebooks", json={
-    "name": "Cancer Genomics Research",
-    "description": "Literature review on tumor mutational burden"
-})
-notebook = response.json()
-notebook_id = notebook["id"]
-```
-
-### Sources
-Ingest diverse content types including PDFs, videos, audio files, web pages, and Office documents. Sources are processed for full-text and vector search.
-
-```python
-# Add a web URL source
-response = requests.post(f"{BASE_URL}/sources", data={
-    "url": "https://arxiv.org/abs/2301.00001",
-    "notebook_id": notebook_id,
-    "process_async": "true"
-})
-source = response.json()
-
-# Upload a PDF file
-with open("paper.pdf", "rb") as f:
-    response = requests.post(
-        f"{BASE_URL}/sources",
-        data={"notebook_id": notebook_id},
-        files={"file": ("paper.pdf", f, "application/pdf")}
-    )
-```
-
-### Notes
-Create and manage notes (human or AI-generated) associated with notebooks.
-
-```python
-# Create a human note
-response = requests.post(f"{BASE_URL}/notes", json={
-    "title": "Key Findings",
-    "content": "TMB correlates with immunotherapy response in NSCLC...",
-    "note_type": "human",
-    "notebook_id": notebook_id
-})
-```
-
-### Context-Aware Chat
-Chat with your research materials using AI that cites sources.
-
-```python
-# Create a chat session
-session = requests.post(f"{BASE_URL}/chat/sessions", json={
-    "notebook_id": notebook_id,
-    "title": "TMB Discussion"
-}).json()
-
-# Send a message with context from sources
-response = requests.post(f"{BASE_URL}/chat/execute", json={
-    "session_id": session["id"],
-    "message": "What are the key biomarkers for immunotherapy response?",
-    "context": {"include_sources": True, "include_notes": True}
-})
-```
-
-### Search
-Search across all materials using full-text or vector (semantic) search.
-
-```python
-# Vector search across the knowledge base
-results = requests.post(f"{BASE_URL}/search", json={
-    "query": "tumor mutational burden immunotherapy",
-    "search_type": "vector",
-    "limit": 10
-}).json()
-
-# Ask a question with AI-powered answer
-answer = requests.post(f"{BASE_URL}/search/ask/simple", json={
-    "query": "How does TMB predict checkpoint inhibitor response?"
-}).json()
-```
-
-### Podcast Generation
-Generate professional multi-speaker podcasts from research materials with 1-4 customizable speakers.
-
-```python
-# Generate a podcast episode
-job = requests.post(f"{BASE_URL}/podcasts/generate", json={
-    "notebook_id": notebook_id,
-    "episode_profile_id": episode_profile_id,
-    "speaker_profile_ids": [speaker1_id, speaker2_id]
-}).json()
-
-# Check generation status
-status = requests.get(f"{BASE_URL}/podcasts/jobs/{job['job_id']}").json()
-
-# Download audio when ready
-audio = requests.get(
-    f"{BASE_URL}/podcasts/episodes/{status['episode_id']}/audio"
-)
-```
-
-### Content Transformations
-Apply custom AI-powered transformations to content for summarization, extraction, and analysis.
-
-```python
-# Create a custom transformation
-transform = requests.post(f"{BASE_URL}/transformations", json={
-    "name": "extract_methods",
-    "title": "Extract Methods",
-    "description": "Extract methodology details from papers",
-    "prompt": "Extract and summarize the methodology section...",
-    "apply_default": False
-}).json()
-
-# Execute transformation on text
-result = requests.post(f"{BASE_URL}/transformations/execute", json={
-    "transformation_id": transform["id"],
-    "input_text": "...",
-    "model_id": "model_id_here"
-}).json()
-```
-
-## Supported AI Providers
-
-Open Notebook supports 16+ AI providers through the Esperanto library:
-
-| Provider | LLM | Embedding | Speech-to-Text | Text-to-Speech |
-|----------|-----|-----------|----------------|----------------|
-| OpenAI | Yes | Yes | Yes | Yes |
-| Anthropic | Yes | No | No | No |
-| Google GenAI | Yes | Yes | No | Yes |
-| Vertex AI | Yes | Yes | No | Yes |
-| Ollama | Yes | Yes | No | No |
-| Groq | Yes | No | Yes | No |
-| Mistral | Yes | Yes | No | No |
-| Azure OpenAI | Yes | Yes | No | No |
-| DeepSeek | Yes | No | No | No |
-| xAI | Yes | No | No | No |
-| OpenRouter | Yes | No | No | No |
-| ElevenLabs | No | No | Yes | Yes |
-| Perplexity | Yes | No | No | No |
-| Voyage | No | Yes | No | No |
-
-## Environment Variables
-
-Key configuration variables for Docker deployment:
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OPEN_NOTEBOOK_ENCRYPTION_KEY` | **Required.** Secret key for encrypting stored credentials | None |
-| `SURREAL_URL` | SurrealDB connection URL | `ws://surrealdb:8000/rpc` |
-| `SURREAL_NAMESPACE` | Database namespace | `open_notebook` |
-| `SURREAL_DATABASE` | Database name | `open_notebook` |
-| `OPEN_NOTEBOOK_PASSWORD` | Optional password protection for the UI | None |
-
-## API Reference
-
-The REST API is available at `http://localhost:5055/api` with interactive documentation at `/docs`.
-
-Core endpoint groups:
-- `/api/notebooks` - Notebook CRUD and source association
-- `/api/sources` - Source ingestion, processing, and retrieval
-- `/api/notes` - Note management
-- `/api/chat/sessions` - Chat session management
-- `/api/chat/execute` - Chat message execution
-- `/api/search` - Full-text and vector search
-- `/api/podcasts` - Podcast generation and management
-- `/api/transformations` - Content transformation pipelines
-- `/api/models` - AI model configuration and discovery
-- `/api/credentials` - Provider credential management
-
-For complete API reference with all endpoints and request/response formats, see `references/api_reference.md`.
-
-## Architecture
-
-Open Notebook uses a modern stack:
-- **Backend:** Python with FastAPI
-- **Database:** SurrealDB (document + relational)
-- **AI Integration:** LangChain with the Esperanto multi-provider library
-- **Frontend:** Next.js with React
-- **Deployment:** Docker Compose with persistent volumes
-
-## Important Notes
-
-- Open Notebook requires Docker for deployment
-- At least one AI provider must be configured for AI features to work
-- For free local inference without API costs, use Ollama
-- The `OPEN_NOTEBOOK_ENCRYPTION_KEY` must be set before first launch and kept consistent across restarts
-- All data is stored locally in Docker volumes for complete data sovereignty