@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/pytdc/SKILL.md

@@ -1,297 +0,0 @@
----
-name: pytdc
-description: Use Therapeutics Data Commons through the PyTDC Python package for registry discovery, approved dataset access, task-aware splits, evaluator metrics, benchmark groups, and bounded molecular-oracle workflows.
-license: MIT
-allowed-tools: Read Write Edit Bash
-compatibility: Requires uv, CPython 3.11, PyTDC 1.1.15, and setuptools 80.9.0 for its legacy pkg_resources runtime import. Dataset, benchmark, checkpoint, and remote-oracle operations require network/storage review and explicit user approval.
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
----
-
-# PyTDC (Therapeutics Data Commons)
-
-Use the official `PyTDC` distribution (`import tdc`) to discover therapeutic ML
-tasks, load approved datasets, apply task-appropriate splits, evaluate predictions,
-and work with curated benchmark groups. Prefer package metadata over copied dataset
-lists, and plan network/storage effects before constructing any loader.
-
-## Verified snapshot
-
-- Research date: **2026-07-23**
-- PyPI stable: **PyTDC 1.1.15**, released 2025-03-31
-- Package/source repository: `mims-harvard/TDC`
-- Code license: MIT
-- PyPI supplies only a source distribution and declares no `Requires-Python`
-- The dependency graph makes **CPython 3.11** the reproducible target used here:
-  `cellxgene-census==1.15.0` excludes Python 3.12, and PyTDC's constrained
-  RDKit release has no CPython 3.13 wheel
-- PyTDC imports deprecated `pkg_resources` at runtime. Setuptools 82 removed that
-  module; pin the verified compatibility release **setuptools 80.9.0**.
-- `tdc.readthedocs.io` still identifies itself as TDC 0.4.1; use it as API
-  cross-reference, not as release-version evidence
-- Upstream publishes no GitHub tags/releases or maintained changelog. Treat
-  undocumented migration claims as uncertainty and verify against the installed
-  1.1.15 source/metadata.
-
-See [references/sources.md](references/sources.md) for dated evidence and known
-documentation conflicts.
-
-## Installation
-
-Use an isolated CPython 3.11 environment and pin the reviewed snapshot:
-
-```bash
-uv venv --python 3.11 .venv-pytdc
-uv pip install --dry-run --python .venv-pytdc/bin/python \
-  "setuptools==80.9.0" "PyTDC==1.1.15"
-uv pip install --python .venv-pytdc/bin/python \
-  "setuptools==80.9.0" "PyTDC==1.1.15"
-```
-
-The tested macOS ARM64 resolution installed 123 packages, including large
-scientific/ML dependencies, so the environment itself can transfer and occupy
-hundreds of megabytes before any dataset is downloaded. Review the dry run and
-available disk first. The direct pins identify the reviewed API snapshot; generate
-a platform-specific `uv.lock` in the user's project when every transitive version
-must also be frozen.
-
-For an ephemeral command:
-
-```bash
-uv run --python 3.11 \
-  --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/discover_metadata.py --kind tasks
-```
-
-To check for a newer release, inspect the PyPI release history at
-<https://pypi.org/project/pytdc/>. Before changing the pin, compare its source
-distribution, dependencies, official repository, task registries, and smoke tests;
-do not silently substitute the separate `pytdc-nextml` package.
-
-## Non-negotiable data and network policy
-
-1. **Discover first.** Reading `tdc.metadata` or using
-   `scripts/discover_metadata.py` does not instantiate a loader or download data.
-2. **Plan second.** Record the exact task/dataset, official task page, license,
-   expected size, cache directory, split, metric, and reproducibility seed.
-3. **Ask the user before downloading.** Loader constructors fetch missing data.
-   Some datasets and benchmark-group archives are large; model-backed oracles can
-   fetch checkpoints; remote/docking oracles can transmit molecular structures.
-4. **Execute only after approval.** In bundled CLIs, `--execute` acknowledges
-   execution and `--download` is additionally required for MolGen corpora or
-   supported oracle checkpoints.
-5. **Keep outputs bounded.** Emit counts, schema, and small previews rather than
-   full datasets, sequences, prediction arrays, or molecule corpora.
-
-### Cache and cost behavior
-
-- Ordinary loaders default to `path="./data"` and save files beneath that path.
-  The bundled scripts instead default to explicit `.pytdc-*` directories.
-- Core downloads use Harvard Dataverse file endpoints when a local filename is
-  absent. Newer resource classes may use other upstream services.
-- `admet_group(path=...)` and other benchmark-group constructors download and
-  extract the group archive when `<path>/<group>` is absent.
-- Download-backed `Oracle(...)` construction uses `./oracle` internally. The
-  bundled oracle CLI changes into a safe runtime directory before approved calls.
-- PyTDC 1.1.15 does not provide a universal cache quota, eviction policy, or
-  dataset-wide checksum manifest. Use `scripts/cache_audit.py` and manage disk
-  retention explicitly.
-- Network transfer, local storage, decompression, parsing, feature generation,
-  docking, and external service calls can all incur time or monetary cost.
-
-The PyTDC **code** is MIT. Dataset/task licenses are heterogeneous: official task
-pages include per-dataset terms ranging from Creative Commons licenses to
-non-commercial restrictions or “Not Specified.” Verify the exact dataset's page and
-original source terms before download, redistribution, publication, or commercial
-use. Cite both TDC and the original dataset.
-
-## Start with metadata-only discovery
-
-From this skill directory:
-
-```bash
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/discover_metadata.py --kind datasets --task ADME --limit 50
-
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/discover_metadata.py --kind benchmarks --limit 50
-
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/discover_metadata.py --kind evaluators --limit 100
-```
-
-The package API is also metadata-only:
-
-```python
-from tdc.utils import retrieve_dataset_names, retrieve_benchmark_names
-
-adme_names = retrieve_dataset_names("ADME")
-admet_benchmarks = retrieve_benchmark_names("admet_group")
-```
-
-Use exact returned names. PyTDC performs fuzzy matching internally, but explicit
-matching avoids silently selecting the wrong dataset/oracle.
-
-## Dataset workflow
-
-Plan a split without downloading:
-
-```bash
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/load_and_split_data.py \
-  --task ADME --dataset Caco2_Wang --method scaffold \
-  --seed 42 --data-dir .pytdc-data
-```
-
-After the user approves the dataset, license, transfer, and storage:
-
-```bash
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/load_and_split_data.py \
-  --task ADME --dataset Caco2_Wang --method scaffold \
-  --seed 42 --data-dir .pytdc-data --execute
-```
-
-Verified public import patterns include:
-
-```python
-from tdc.single_pred import ADME, Tox
-from tdc.multi_pred import DDI, DTI
-from tdc.generation import MolGen, Reaction, RetroSyn
-```
-
-Constructors perform data access, so do not run them before approval:
-
-```python
-data = ADME(name="Caco2_Wang", path=".pytdc-data")
-frame = data.get_data(format="df")
-split = data.get_split(
-    method="scaffold",
-    seed=42,
-    frac=[0.7, 0.1, 0.2],
-)
-# split keys are: train, valid, test
-```
-
-Read [references/datasets.md](references/datasets.md) before choosing a task or
-dataset.
-
-## Split selection without overclaiming leakage control
-
-- `random`: default for loaders; default seed 42 and fractions 0.7/0.1/0.2.
-- `scaffold`: documented generic support for molecule-based ADME, Tox, and HTS.
-  PyTDC groups RDKit Bemis–Murcko scaffold strings (chirality disabled), but that
-  does **not** prove absence of analog, duplicate, label, temporal, or provenance
-  leakage.
-- `cold_split`: multi-instance API. Pass exact dataframe columns, for example
-  `method="cold_split", column_name=["Drug", "Target"]`. Multi-column splitting can
-  discard cross-partition rows and need not preserve requested row fractions.
-- `combination`: built-in DrugSyn combination split.
-- `time`: pair-loader API requiring `time_column`; the verified built-in case is
-  `BindingDB_Patent` with its `Year` column. The API spelling is `time`, not
-  `temporal`.
-
-Do not use undocumented `cold_drug_target`, `temporal`, or `stratified=True`
-examples. For every split, record PyTDC version, parameters, row counts, and exact
-entity overlap audits. PyTDC 1.1.15's random splitter uses the supplied seed for
-test sampling but a fixed `random_state=1` for validation sampling; do not describe
-all partitions as independently varying with the seed.
-
-Detailed semantics and caveats are in
-[references/utilities.md](references/utilities.md).
-
-## Evaluators
-
-Use exact names from the installed evaluator registry:
-
-```python
-from tdc import Evaluator
-
-mae = Evaluator(name="MAE")(y_true, y_pred)
-auroc = Evaluator(name="ROC-AUC")(y_true_binary, predicted_scores)
-pcc = Evaluator(name="PCC")(y_true, y_pred)
-```
-
-`PCC` is the registered Pearson-correlation name; `Pearson` is not. Multi-class
-registry names are `micro-f1`, `macro-f1`, and `kappa`. Thresholded binary metrics
-default to 0.5. Metric direction and input shape are metric-specific; use the
-official task/benchmark metric rather than choosing from task type alone.
-
-## Benchmark groups
-
-Use specialized classes. Top-level `from tdc import BenchmarkGroup` is retained
-only as a deprecated compatibility path in 1.1.15.
-
-```python
-from tdc.benchmark_group import admet_group
-
-# Run only after approval: construction may download the group archive.
-group = admet_group(path=".pytdc-benchmarks")
-benchmark = group.get("Caco2_Wang")
-train_val = benchmark["train_val"]
-test = benchmark["test"]
-train, valid = group.get_train_valid_split(
-    seed=1,
-    benchmark=benchmark["name"],
-    split_type="default",
-)
-```
-
-For one run, `group.evaluate({name: test_predictions})` returns metric results.
-For leaderboard aggregation, pass a **list of at least five prediction
-dictionaries** to `group.evaluate_many(...)`. Do not index `group.get(...)` by
-seed, and do not derive dummy predictions from test labels.
-
-Use `scripts/benchmark_evaluation.py` to validate a bounded JSON prediction plan
-before any group download. See [references/utilities.md](references/utilities.md)
-for the exact JSON shape and API behavior.
-
-## Molecular generation and oracles
-
-PyTDC supplies molecule corpora, evaluators, and oracles; it does not train or
-provide a generic molecule generator in the core workflow. Discover current names:
-
-```bash
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/discover_metadata.py --kind oracles --limit 100
-```
-
-Plan bounded local QED scoring:
-
-```bash
-uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
-  python scripts/molecular_generation.py score --oracle QED --smiles CCO
-```
-
-Add `--execute` only after review. LogP and SA call the downloadable `fpscores`
-artifact in 1.1.15; they and DRD2/GSK3B/JNK3/CYP3A4_Veith also require
-`--download`. The helper intentionally refuses remote services, docking,
-distribution, and composite oracles. It preserves input order and never assumes
-score direction.
-
-Read [references/oracles.md](references/oracles.md) before any oracle call.
-
-## Bundled resources
-
-### Scripts
-
-- `scripts/discover_metadata.py` — download-free package registry discovery
-- `scripts/load_and_split_data.py` — task-aware split plan/explicit execution
-- `scripts/benchmark_evaluation.py` — prediction validation and explicit evaluation
-- `scripts/molecular_generation.py` — bounded local/checkpoint scoring and MolGen plan
-- `scripts/cache_audit.py` — read-only bounded cache manifest
-
-Every CLI uses lazy optional imports, safe relative output/cache paths, JSON
-summaries, bounded output, and no implicit dataset/model download.
-
-### References
-
-- [references/datasets.md](references/datasets.md) — task discovery, data access,
-  cache behavior, and licensing
-- [references/utilities.md](references/utilities.md) — splits, evaluators, and
-  benchmark-group APIs
-- [references/oracles.md](references/oracles.md) — oracle categories, side effects,
-  and safe execution
-- [references/sources.md](references/sources.md) — dated authoritative sources and
-  unresolved upstream gaps

package/skills/pytorch-lightning/SKILL.md

@@ -1,191 +0,0 @@
----
-name: pytorch-lightning
-description: Deep learning framework (PyTorch Lightning / lightning package). Organize PyTorch code into LightningModules, configure Trainers for multi-GPU/TPU, implement data pipelines, callbacks, logging (W&B, TensorBoard, MLflow), distributed training (DDP, FSDP, DeepSpeed), for scalable neural network training.
-allowed-tools: Read Write Edit Bash
-license: Apache-2.0 license
-compatibility: Requires Python 3.10+ and lightning 2.6+ (or pytorch-lightning 2.6+). GPU training needs CUDA-capable PyTorch. Optional loggers (wandb, mlflow, comet-ml) and DeepSpeed require separate installs.
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
----
-
-# PyTorch Lightning
-
-## Overview
-
-PyTorch Lightning is a deep learning framework that organizes PyTorch code to eliminate boilerplate while maintaining full flexibility. Automate training workflows, multi-device orchestration, and implement best practices for neural network training and scaling across multiple GPUs/TPUs.
-
-**Current upstream:** lightning 2.6.4 (PyPI, May 2026). Docs: [lightning.ai/docs/pytorch/stable](https://lightning.ai/docs/pytorch/stable/). Use `import lightning as L` (the `pytorch-lightning` package name still installs the same library).
-
-## Installation
-
-```bash
-uv pip install lightning
-```
-
-Optional extras:
-
-```bash
-uv pip install lightning[extra]    # loggers, strategies, etc.
-uv pip install wandb mlflow        # specific loggers as needed
-```
-
-## When to Use This Skill
-
-This skill should be used when:
-- Building, training, or deploying neural networks using PyTorch Lightning
-- Organizing PyTorch code into LightningModules
-- Configuring Trainers for multi-GPU/TPU training
-- Implementing data pipelines with LightningDataModules
-- Working with callbacks, logging, and distributed training strategies (DDP, FSDP, DeepSpeed)
-- Structuring deep learning projects professionally
-
-## Core Capabilities
-
-### 1. LightningModule - Model Definition
-
-Organize PyTorch models into six logical sections:
-
-1. **Initialization** - `__init__()` and `setup()`
-2. **Training Loop** - `training_step(batch, batch_idx)`
-3. **Validation Loop** - `validation_step(batch, batch_idx)`
-4. **Test Loop** - `test_step(batch, batch_idx)`
-5. **Prediction** - `predict_step(batch, batch_idx)`
-6. **Optimizer Configuration** - `configure_optimizers()`
-
-**Quick template reference:** See `scripts/template_lightning_module.py` for a complete boilerplate.
-
-**Detailed documentation:** Read `references/lightning_module.md` for comprehensive method documentation, hooks, properties, and best practices.
-
-### 2. Trainer - Training Automation
-
-The Trainer automates the training loop, device management, gradient operations, and callbacks. Key features:
-
-- Multi-GPU/TPU support with strategy selection (DDP, FSDP, DeepSpeed)
-- Automatic mixed precision training
-- Gradient accumulation and clipping
-- Checkpointing and early stopping
-- Progress bars and logging
-
-**Quick setup reference:** See `scripts/quick_trainer_setup.py` for common Trainer configurations.
-
-**Detailed documentation:** Read `references/trainer.md` for all parameters, methods, and configuration options.
-
-### 3. LightningDataModule - Data Pipeline Organization
-
-Encapsulate all data processing steps in a reusable class:
-
-1. `prepare_data()` - Download and process data (single-process)
-2. `setup()` - Create datasets and apply transforms (per-GPU)
-3. `train_dataloader()` - Return training DataLoader
-4. `val_dataloader()` - Return validation DataLoader
-5. `test_dataloader()` - Return test DataLoader
-
-**Quick template reference:** See `scripts/template_datamodule.py` for a complete boilerplate.
-
-**Detailed documentation:** Read `references/data_module.md` for method details and usage patterns.
-
-### 4. Callbacks - Extensible Training Logic
-
-Add custom functionality at specific training hooks without modifying your LightningModule. Built-in callbacks include:
-
-- **ModelCheckpoint** - Save best/latest models
-- **EarlyStopping** - Stop when metrics plateau
-- **LearningRateMonitor** - Track LR scheduler changes
-- **BatchSizeFinder** - Auto-determine optimal batch size
-
-**Detailed documentation:** Read `references/callbacks.md` for built-in callbacks and custom callback creation.
-
-### 5. Logging - Experiment Tracking
-
-Integrate with multiple logging platforms:
-
-- TensorBoard (default)
-- Weights & Biases (WandbLogger)
-- MLflow (MLFlowLogger)
-- Comet (CometLogger)
-- CSV (CSVLogger)
-
-Note: `NeptuneLogger` was removed in lightning 2.6.4. Use W&B, MLflow, or TensorBoard instead.
-
-Log metrics using `self.log("metric_name", value)` in any LightningModule method.
-
-**Detailed documentation:** Read `references/logging.md` for logger setup and configuration.
-
-### 6. Distributed Training - Scale to Multiple Devices
-
-Choose the right strategy based on model size:
-
-- **DDP** - For models <500M parameters (ResNet, smaller transformers)
-- **FSDP** - For models 500M+ parameters (large transformers, recommended for Lightning users)
-- **DeepSpeed** - For cutting-edge features and fine-grained control
-
-Configure with: `Trainer(strategy="ddp", accelerator="gpu", devices=4)`
-
-**Detailed documentation:** Read `references/distributed_training.md` for strategy comparison and configuration.
-
-### 7. Best Practices
-
-- Device agnostic code - Use `self.device` instead of `.cuda()`
-- Hyperparameter saving - Use `self.save_hyperparameters()` in `__init__()`
-- Metric logging - Use `self.log()` for automatic aggregation across devices
-- Reproducibility - Use `seed_everything()` and `Trainer(deterministic=True)`
-- Debugging - Use `Trainer(fast_dev_run=True)` to test with 1 batch
-
-**Detailed documentation:** Read `references/best_practices.md` for common patterns and pitfalls.
-
-## Quick Workflow
-
-1. **Define model:**
-   ```python
-   class MyModel(L.LightningModule):
-       def __init__(self):
-           super().__init__()
-           self.save_hyperparameters()
-           self.model = YourNetwork()
-
-       def training_step(self, batch, batch_idx):
-           x, y = batch
-           loss = F.cross_entropy(self.model(x), y)
-           self.log("train_loss", loss)
-           return loss
-
-       def configure_optimizers(self):
-           return torch.optim.Adam(self.parameters())
-   ```
-
-2. **Prepare data:**
-   ```python
-   # Option 1: Direct DataLoaders
-   train_loader = DataLoader(train_dataset, batch_size=32)
-
-   # Option 2: LightningDataModule (recommended for reusability)
-   dm = MyDataModule(batch_size=32)
-   ```
-
-3. **Train:**
-   ```python
-   trainer = L.Trainer(max_epochs=10, accelerator="gpu", devices=2)
-   trainer.fit(model, train_loader)  # or trainer.fit(model, datamodule=dm)
-   ```
-
-## Resources
-
-### scripts/
-Executable Python templates for common PyTorch Lightning patterns:
-
-- `template_lightning_module.py` - Complete LightningModule boilerplate
-- `template_datamodule.py` - Complete LightningDataModule boilerplate
-- `quick_trainer_setup.py` - Common Trainer configuration examples
-
-### references/
-Detailed documentation for each PyTorch Lightning component:
-
-- `lightning_module.md` - Comprehensive LightningModule guide (methods, hooks, properties)
-- `trainer.md` - Trainer configuration and parameters
-- `data_module.md` - LightningDataModule patterns and methods
-- `callbacks.md` - Built-in and custom callbacks
-- `logging.md` - Logger integrations and usage
-- `distributed_training.md` - DDP, FSDP, DeepSpeed comparison and setup
-- `best_practices.md` - Common patterns, tips, and pitfalls
-

package/skills/pyzotero/SKILL.md

@@ -1,137 +0,0 @@
----
-name: pyzotero
-description: Interact with Zotero reference management libraries using the pyzotero Python client. Retrieve, create, update, and delete items, collections, tags, and attachments via the Zotero Web API v3. Use this skill when working with Zotero libraries programmatically, managing bibliographic references, exporting citations, searching library contents, uploading PDF attachments, or building research automation workflows that integrate with Zotero.
-allowed-tools: Read Write Edit Bash
-license: MIT License
-compatibility: Requires Python 3.10+ and pyzotero 1.13+. Web API access needs a Zotero API key. Optional CLI and MCP extras require Zotero 7 with local API access enabled.
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
-  openclaw:
-    primaryEnv: ZOTERO_API_KEY
-    envVars:
-    - name: ZOTERO_API_KEY
-      required: true
-      description: Zotero API key.
-    - name: ZOTERO_LIBRARY_ID
-      required: true
-      description: Zotero library id.
-    - name: ZOTERO_LIBRARY_TYPE
-      required: false
-      description: 'Zotero library type: ''user'' or ''group'' (default ''user'').'
----
-
-# Pyzotero
-
-Pyzotero is a Python wrapper for the [Zotero API v3](https://www.zotero.org/support/dev/web_api/v3/start). Use it to programmatically manage Zotero libraries: read items and collections, create and update references, upload attachments, manage tags, and export citations.
-
-**Current upstream:** pyzotero 1.13.0 (PyPI, May 2026). Docs: [pyzotero.readthedocs.io](https://pyzotero.readthedocs.io/en/latest/).
-
-## Authentication Setup
-
-**Required credentials** — get from https://www.zotero.org/settings/keys:
-- **User ID**: shown as "Your userID for use in API calls"
-- **API Key**: create at https://www.zotero.org/settings/keys/new
-- **Library ID**: for group libraries, the integer after `/groups/` in the group URL
-
-Store credentials in environment variables or a `.env` file:
-```
-ZOTERO_LIBRARY_ID=your_user_id
-ZOTERO_API_KEY=your_api_key
-ZOTERO_LIBRARY_TYPE=user  # or "group"
-```
-
-See [references/authentication.md](references/authentication.md) for full setup details.
-
-## Installation
-
-```bash
-uv add pyzotero              # Web API client
-uv add "pyzotero[cli]"       # + local CLI (Zotero 7)
-uv add "pyzotero[mcp]"       # + MCP server for LLM clients (Zotero 7)
-```
-
-## Quick Start
-
-```python
-import os
-from pyzotero import Zotero
-
-zot = Zotero(
-    library_id=os.environ['ZOTERO_LIBRARY_ID'],
-    library_type=os.environ.get('ZOTERO_LIBRARY_TYPE', 'user'),
-    api_key=os.environ['ZOTERO_API_KEY'],
-)
-
-# Retrieve top-level items (returns 100 by default)
-items = zot.top(limit=10)
-for item in items:
-    print(item['data']['title'], item['data']['itemType'])
-
-# Search by keyword
-results = zot.items(q='machine learning', limit=20)
-
-# Retrieve all items (use everything() for complete results)
-all_items = zot.everything(zot.items())
-```
-
-## Core Concepts
-
-- A `Zotero` instance is bound to a single library (user or group). All methods operate on that library.
-- Item data lives in `item['data']`. Access fields like `item['data']['title']`, `item['data']['creators']`.
-- Pyzotero returns 100 items by default (API default is 25). Use `zot.everything(zot.items())` to get all items.
-- Write methods return `True` on success or raise a `ZoteroError`.
-
-## Reference Files
-
-| File | Contents |
-|------|----------|
-| [references/authentication.md](references/authentication.md) | Credentials, library types, local mode |
-| [references/read-api.md](references/read-api.md) | Retrieving items, collections, tags, groups |
-| [references/search-params.md](references/search-params.md) | Filtering, sorting, search parameters |
-| [references/write-api.md](references/write-api.md) | Creating, updating, deleting items |
-| [references/collections.md](references/collections.md) | Collection CRUD operations |
-| [references/tags.md](references/tags.md) | Tag access and management |
-| [references/files-attachments.md](references/files-attachments.md) | File download and attachment uploads |
-| [references/exports.md](references/exports.md) | BibTeX, CSL-JSON, bibliography export |
-| [references/pagination.md](references/pagination.md) | follow(), everything(), generators |
-| [references/full-text.md](references/full-text.md) | Full-text content indexing and access |
-| [references/saved-searches.md](references/saved-searches.md) | Saved search management |
-| [references/cli.md](references/cli.md) | Command-line interface (local Zotero 7) |
-| [references/mcp.md](references/mcp.md) | MCP server for LLM clients (local Zotero 7) |
-| [references/error-handling.md](references/error-handling.md) | Errors and exception handling |
-
-## Common Patterns
-
-### Fetch and modify an item
-```python
-item = zot.item('ITEMKEY')
-item['data']['title'] = 'New Title'
-zot.update_item(item)
-```
-
-### Create an item from a template
-```python
-template = zot.item_template('journalArticle')
-template['title'] = 'My Paper'
-template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
-zot.create_items([template])
-```
-
-### Export as BibTeX
-```python
-zot.add_parameters(format='bibtex')
-bibtex = zot.top(limit=50)
-# bibtex is a bibtexparser BibDatabase object
-print(bibtex.entries)
-```
-
-### Local mode (read-only, no API key needed)
-```python
-zot = Zotero(library_id='123456', library_type='user', local=True)
-items = zot.items()
-```
-
-### Local Zotero 7 (CLI or MCP, no API key)
-
-For searching a locally running Zotero desktop app (including full-text PDF search), use the CLI or MCP server instead of the Web API. Both require Zotero 7 with local API access enabled. See [references/cli.md](references/cli.md) and [references/mcp.md](references/mcp.md).