# YAMS Plugins: Overview and Spec

This document is an entry point for YAMS plugin development. The authoritative
specification lives at `docs/spec/plugin_spec.md`.

- Spec: docs/spec/plugin_spec.md
- C‑ABI core: include/yams/plugins/abi.h
  - `yams_plugin_init` receives an optional host context to call back into YAMS services.
- Interfaces:
  - Plugin-provided (called by host):
    - Model provider (v1): include/yams/plugins/model_provider_v1.h
    - Object storage (v1): include/yams/plugins/object_storage_v1.h (if present)
  - Host-provided (called by plugin):
    - Host Services (v1): include/yams/plugins/host_services_v1.h
      - Exposes core application services like Document and Search to plugins.

Quick start
- Discover plugins: `yams plugin scan [dir|file]`
- Trust a plugin: `yams plugin trust add /path/to/plugin.so`
- List trusted: `yams plugin trust list`
- Load on daemon start: place plugins in a trusted directory or set `plugin_dir` in config.

Loading custom plugins at daemon start
- Search order (first match wins per provider):
  1) Configured directories (daemon config `plugin_dir` or multiple `plugin_dirs` when supported)
  2) Env override (deprecated): `YAMS_PLUGIN_DIR`
  3) User: `$HOME/.local/lib/yams/plugins`
  4) System: `/usr/local/lib/yams/plugins`, `/usr/lib/yams/plugins`
  5) Install prefix: `${CMAKE_INSTALL_PREFIX}/lib/yams/plugins`

- Trust policy (default deny):
  - Trust file: `~/.config/yams/plugins_trust.txt` (one absolute path per line, directories or files)
  - CLI helpers:
    - `yams plugin trust add /path/to/dir-or-file`
    - `yams plugin trust remove /path/to/dir-or-file`
  - Dev override (use with caution): `YAMS_PLUGIN_TRUST_ALL=1` trusts paths found via search order.

- De-duplication and naming (Linux/macOS):
  - The daemon prefers non-`lib` prefixed filenames when both `libyams_foo_plugin.*` and
    `yams_foo_plugin.*` exist in the same directory.
  - Providers are de-duplicated by logical name: only one implementation is adopted by priority
    (user dir > system dir; non-`lib` filename > `lib` filename).

Name policy (display identity and selection)
- The daemon accepts a name policy for ABI plugins that influences how plugin names are presented
  and deduplicated:
  - `Relaxed` (default): derive a canonical name from filename (e.g., strip leading `lib` from
    `libyams_foo_plugin`) when manifest does not specify a name. Deduplicate variants by canonical
    name.
  - `Spec`: respect the plugin’s manifest `name` field verbatim for display and selection.
    De-duplication still merges file variants that implement the same provider.

- Configure the policy:
  - Env: `YAMS_PLUGIN_NAME_POLICY=spec|relaxed`
  - Daemon config: `plugin_name_policy: spec|relaxed` (when available)

Examples
```
# Build or download your plugin to a user dir, trust it, and restart daemon
mkdir -p ~/.local/lib/yams/plugins
cp ./build/plugins/my_plugin/yams_my_plugin.dylib ~/.local/lib/yams/plugins/   # macOS
cp ./build/plugins/my_plugin/libyams_my_plugin.so ~/.local/lib/yams/plugins/    # Linux
yams plugin trust add ~/.local/lib/yams/plugins
yams daemon restart

# Enforce spec naming (use manifest name in listings)
export YAMS_PLUGIN_NAME_POLICY=spec
yams plugins list
```

Runtime notes
- The daemon prefers a host‑backed `model_provider_v1` plugin for embeddings; otherwise it
  falls back to the built‑in registry or mock/null providers.
- Progress events (ModelLoadEvent) may be emitted during model preload or warmup.

Model Provider (model_provider_v1)
- Interface version: v1.2 (pre‑stable). Header: `include/yams/plugins/model_provider_v1.h`.
- Base API: load/unload, single/batch embeddings.
- New in 1.2 (pre‑stable additions):
  - `get_embedding_dim(self, model_id, out_dim)` — fast dimension lookup.
  - `get_runtime_info_json(self, model_id, out_json)` — JSON with runtime details; free via `free_string`:
    `{ "backend": "onnxruntime|genai", "pipeline": "raw_ort|genai", "model": "all-mpnet-base-v2", "dim": 384, "intra_threads": 8, "inter_threads": 1, "runtime_version": "x.y.z" }`
  - `set_threading(self, model_id, intra_threads, inter_threads)` — optional; may return UNSUPPORTED.

Adoption and telemetry
- Plugins should advertise `{ id: "model_provider_v1", version: 2 }` in their manifest.
- The daemon can probe alt versions for backward compatibility, but v2 (v1.2) is recommended.
- Daemon status surfaces embedding runtime info (backend/model/dim/threads) when available.

SDK
- In‑repo SDK: external/yams-sdk (Python‑first; JSON‑RPC helpers, templates, conformance runner)
- Mirror: https://git.sr.ht/~trvon/yams-sdk
- Templates: external/yams-sdk/python/templates (e.g., external-dr)
- SDK‑driven tests: yams/tests/sdk (exercise handshake/call/conformance without the daemon)

For detailed vtables, error mapping, lifecycle, and security/trust policy, see:
- docs/spec/plugin_spec.md
- spec/plugin_naming_and_loading.md (naming, discovery, trust, dedupe; Linux/macOS)