{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Deliverables Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/deliverables-tools",
  "summary": "Search, retrieve, and register work products. Semantic search over previously produced charts, exports, data, and reports.",
  "content_markdown": "# Deliverables Tools\n\nSearch, retrieve, and register work products. Semantic search over previously produced charts, exports, data, and reports.\n\nDeliverables are permanent records of work products — everything from auto-captured chart outputs to explicitly packaged analysis results. Unlike ephemerals (which vanish when their cache TTL expires), deliverables persist in the database indefinitely with encrypted-at-rest payloads.\n\n---\n\n## `deliverables.list@1`\n\nSearch and list previously produced work products. When a `query` is provided, uses **semantic search** via pgvector embeddings — describe what you're looking for in natural language rather than exact keywords. Falls back to standard text filtering when embeddings are unavailable.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `type` | string | no | all | Filter by type: `\"chart\"`, `\"export\"`, `\"data\"`, `\"content\"`, `\"report\"` |\n| `query` | string | no | -- | Semantic search — describe what you're looking for (e.g. `\"revenue analysis from last quarter\"`) |\n| `agent_id` | integer | no | -- | Filter by producing agent ID |\n| `limit` | integer | no | 20 | Max results (max 100) |\n| `offset` | integer | no | 0 | Pagination offset |\n\n### Example — Semantic Search\n\n```json\n{\n  \"name\": \"data-grout@1/deliverables.list@1\",\n  \"arguments\": {\n    \"query\": \"customer churn analysis\"\n  }\n}\n```\n\n### Example — Type Filter\n\n```json\n{\n  \"name\": \"data-grout@1/deliverables.list@1\",\n  \"arguments\": {\n    \"type\": \"chart\",\n    \"limit\": 5\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"deliverables\": [\n    {\n      \"ref\": \"del_a1b2c3d4e5f6\",\n      \"type\": \"chart\",\n      \"title\": \"Monthly Revenue Trend\",\n      \"summary\": \"Line chart of revenue by month for Q1 2026\",\n      \"created_at\": \"2026-03-15T05:00:00Z\",\n      \"agent_name\": \"Finance Agent\",\n      \"has_cache_ref\": false\n    }\n  ],\n  \"total\": 12,\n  \"limit\": 5,\n  \"offset\": 0,\n  \"search_mode\": \"semantic\",\n  \"message\": \"12 deliverables found (semantic match). Use deliverables.get with a ref for full details.\"\n}\n```\n\n### Cost\n\n0 credits — database/embedding query only.\n\n---\n\n## `deliverables.get@1`\n\nRetrieve a specific deliverable by its ref. Returns the full payload and metadata.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `ref` | string | yes | -- | Deliverable ref (e.g. `\"del_a1b2c3d4e5f6\"`) |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/deliverables.get@1\",\n  \"arguments\": {\n    \"ref\": \"del_a1b2c3d4e5f6\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"ref\": \"del_a1b2c3d4e5f6\",\n  \"type\": \"chart\",\n  \"title\": \"Monthly Revenue Trend\",\n  \"summary\": \"Line chart of revenue by month for Q1 2026\",\n  \"payload\": {\n    \"image_url\": \"https://...\",\n    \"sparkline\": \"▁▂▃▅▇\"\n  },\n  \"metadata\": {\n    \"source_type\": \"auto\",\n    \"tool_name\": \"prism.chart\"\n  },\n  \"created_at\": \"2026-03-15T05:00:00Z\",\n  \"agent\": {\"id\": 42, \"name\": \"Finance Agent\"},\n  \"run_id\": 123\n}\n```\n\n### Cost\n\n0 credits.\n\n---\n\n## `deliverables.register@1`\n\nExplicitly package and register a work product as a deliverable for permanent storage.\n\nUse this to promote ephemeral cached data or to package any result for later retrieval. Registered deliverables appear in `deliverables.list` even after the original cache entry expires.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `title` | string | yes | -- | Human-readable title |\n| `type` | string | yes | -- | `\"chart\"`, `\"export\"`, `\"data\"`, `\"content\"`, `\"report\"` |\n| `summary` | string | no | -- | Brief description |\n| `payload` | object | no | `{}` | The deliverable content (data, URLs, etc.) |\n| `cache_ref` | string | no | -- | Reference to cached data to attach |\n| `tags` | array | no | `[]` | Tags for categorization |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/deliverables.register@1\",\n  \"arguments\": {\n    \"title\": \"Q1 Revenue Analysis\",\n    \"type\": \"data\",\n    \"summary\": \"Filtered and aggregated revenue data for Q1 2026\",\n    \"cache_ref\": \"rc_abc123\",\n    \"tags\": [\"revenue\", \"q1\", \"2026\"]\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"ref\": \"del_f6e5d4c3b2a1\",\n  \"type\": \"data\",\n  \"title\": \"Q1 Revenue Analysis\",\n  \"status\": \"registered\",\n  \"message\": \"Deliverable registered. Use deliverables.get with ref 'del_f6e5d4c3b2a1' to retrieve.\"\n}\n```\n\n### Cost\n\n0 credits.\n\n---\n\n## Lifecycle: Ephemeral → Deliverable\n\n1. A tool call produces data and returns a `cache_ref`\n2. The cached result is visible via `ephemerals.list`\n3. You can inspect it with `ephemerals.inspect`\n4. To keep it permanently, call `deliverables.register` with the `cache_ref`\n5. The deliverable persists in the database even after the cache entry expires\n6. Find it later via `deliverables.list` or `deliverables.get`\n\n## When to use which tool\n\n| Situation | Tool |\n|-----------|------|\n| See what work products have been created | `list` |\n| Get the full content of a deliverable | `get` |\n| Save ephemeral data or results permanently | `register` |\n"
}