@kinetica/admin-agent 0.1.0

package/knowledge/references/sql-create-index.md

@@ -0,0 +1,49 @@
+---
+title: Kinetica CREATE INDEX / DROP INDEX Syntax
+category: sql-syntax
+keywords: [create-index, drop-index, index, ki_indexes, if-not-exists, explain, query-optimization]
+---
+
+## Overview
+
+Kinetica's `CREATE INDEX` syntax differs from standard SQL in two
+places worth flagging up front:
+
+1. The index name is **required** and goes **before** `ON` — there is
+   no "unnamed index" form.
+2. Kinetica does NOT support `IF NOT EXISTS` — you must check
+   `ki_catalog.ki_indexes` before creating an index to avoid a
+   duplicate-name error.
+
+## Syntax
+
+```sql
+-- Single column:
+CREATE INDEX index_name ON [schema.]table_name (column_name)
+
+-- Multiple columns (composite index):
+CREATE INDEX index_name ON [schema.]table_name (col1, col2)
+
+-- Drop an index:
+DROP INDEX index_name ON [schema.]table_name
+```
+
+## Key Rules
+
+- **Index name is REQUIRED and goes BEFORE `ON`:**
+  - Correct: `CREATE INDEX idx_user_email ON users (email)`
+  - WRONG: `CREATE INDEX ON users (email)` — syntax error
+- **No `IF NOT EXISTS`:** Kinetica rejects this clause. Before
+  creating an index, query `ki_catalog.ki_indexes` to see whether
+  an index already covers the column(s). Skipping this check and
+  retrying on failure is wasted work and pollutes audit logs.
+- **Verify with `kinetica_explain_query`:** run
+  `kinetica_explain_query` on the target query both BEFORE and AFTER
+  index creation. The plan should show the new index being used;
+  if it isn't, either the query doesn't benefit from the index or
+  the statistics haven't caught up — there is no
+  `ANALYZE TABLE` to force stats refresh (see
+  `version-quirks-7.2.md`).
+- **Naming convention:** prefer `idx_<table>_<column>` or
+  `idx_<table>_<cols>_<purpose>` so index names stay discoverable in
+  `ki_catalog.ki_indexes`.

package/knowledge/references/tiered-objects.md

@@ -0,0 +1,106 @@
+---
+title: ki_tiered_objects Reference
+category: storage
+keywords: [tiered, tier, storage, RAM, PERSIST, DISK, VRAM, eviction, memory pressure]
+---
+
+## Overview
+
+`ki_catalog.ki_tiered_objects` tracks per-chunk tier placement for every data object across all ranks. Each row represents one chunk of data (a column segment, index fragment, etc.) and where it currently lives in the storage hierarchy.
+
+**Two ways to check tier placement:**
+
+- **`kinetica_resource_objects`** (REST tool) — pre-aggregated per-table view via `/show/resource/objects`. Accepts `table_names` filter. Best for checking a specific table's tier distribution.
+- **`ki_catalog.ki_tiered_objects`** (SQL) — per-chunk granularity. Best for aggregate analysis across all objects, eviction diagnostics, and memory pressure investigation.
+
+## The `id` Column — NOT a Numeric OID
+
+**CRITICAL:** `id` is a `char256` string identifier, NOT a numeric OID. Do NOT join with `ki_objects.oid`.
+
+Format: `@<table_name>@<internal_id>[<type>][<chunk>]`
+Example: `@nyctaxi@365[col][0]`
+
+To filter for a specific table in SQL:
+
+```sql
+WHERE id LIKE '%table_name%'
+```
+
+For structured per-table tier data, prefer `kinetica_resource_objects` with `table_names` filter instead of SQL joins.
+
+## Column Reference
+
+| Column                 | Type    | Meaning                                          | Diagnostic Use                                 |
+| ---------------------- | ------- | ------------------------------------------------ | ---------------------------------------------- |
+| `size`                 | long    | Bytes occupied in current tier                   | Identify large objects consuming tier capacity |
+| `id`                   | char256 | String object identifier (see above)             | Filter by table name via LIKE                  |
+| `priority`             | int     | Eviction priority (1=system, 5=user, 9=temp)     | Higher priority = evicted last                 |
+| `tier`                 | char32  | Current storage tier (RAM, PERSIST, DISK0, VRAM) | Identify what's where                          |
+| `evictable`            | boolean | Tier manager can evict to lower tier             | Find non-evictable objects blocking space      |
+| `locked`               | boolean | Pinned in current tier                           | Locked objects cannot be evicted               |
+| `pin_count`            | int     | Active reference count                           | High pin_count = actively used                 |
+| `ram_evictions`        | int     | Times evicted from RAM                           | High count = memory pressure thrashing         |
+| `persist_evictions`    | int     | Times evicted from PERSIST                       | High count = persist tier pressure             |
+| `owner_resource_group` | char128 | Resource group that owns allocation              | Tie back to resource group limits              |
+| `source_rank`          | int     | Which rank holds this chunk                      | Per-rank tier analysis                         |
+| `outer_object`         | char256 | Parent object name (nullable)                    | Object hierarchy                               |
+
+## Tier Hierarchy
+
+Data flows down when evicted under memory pressure:
+
+```
+VRAM (GPU memory) → RAM (main memory) → PERSIST (permanent storage) → DISK0 (swap cache)
+```
+
+**Priority values determine eviction order** within a tier:
+
+- **1** — system tables (`ki_catalog.*`), evicted last
+- **5** — user tables, standard eviction behavior
+- **9** — temporary/ephemeral, evicted first
+
+**Eviction semantics:**
+
+- `evictable=true` — tier manager can move to a lower tier under pressure
+- `locked=true` — pinned in current tier, will NOT be evicted regardless of pressure
+- When both are false, the object is at rest but not pinned
+
+## Common Diagnostic Queries
+
+```sql
+-- Objects NOT in RAM (potential memory pressure — data has been evicted)
+SELECT id, tier, size, source_rank, owner_resource_group
+FROM ki_catalog.ki_tiered_objects
+WHERE tier != 'VRAM' AND tier != 'RAM'
+ORDER BY size DESC
+LIMIT 20;
+
+-- Per-table tier distribution (replace <table_name>)
+SELECT tier, COUNT(*) AS chunks, SUM(size) AS total_bytes
+FROM ki_catalog.ki_tiered_objects
+WHERE id LIKE '%<table_name>%'
+GROUP BY tier;
+
+-- Locked objects preventing eviction
+SELECT id, tier, size, source_rank, owner_resource_group
+FROM ki_catalog.ki_tiered_objects
+WHERE locked = 1
+ORDER BY size DESC
+LIMIT 20;
+
+-- Objects with high eviction churn (memory pressure indicator)
+SELECT id, tier, size, ram_evictions, persist_evictions, source_rank
+FROM ki_catalog.ki_tiered_objects
+WHERE ram_evictions > 0 OR persist_evictions > 0
+ORDER BY ram_evictions + persist_evictions DESC
+LIMIT 20;
+```
+
+## Key Gotchas
+
+- **Rank 0 has no tiered objects** — it is the head/coordinator node with metadata only. All tiered objects are on worker ranks (1+).
+- **VRAM tier only exists when GPUs are present** — on CPU-only clusters, the highest tier is RAM.
+- **`outer_object` is nullable** — not all objects have a parent; NULL means top-level object.
+- **`source_rank` is dict-encoded** — efficient for filtering/grouping, but values are integers representing rank numbers.
+- **Empty results are normal for small datasets** — if all data fits in RAM, there may be no objects on lower tiers.
+- **`size` is per-chunk, not per-table** — to get total table size in a tier, SUM(size) with a LIKE filter on the table name.

package/knowledge/references/version-quirks-7.2.md

@@ -0,0 +1,96 @@
+---
+title: Kinetica 7.2.x Version Quirks
+category: version-compat
+keywords:
+  [
+    7.2,
+    version,
+    quirks,
+    limitations,
+    analyze-table,
+    verifydb,
+    shard-key,
+    ki_tables,
+    ki_version,
+    rebalance,
+  ]
+---
+
+## Overview
+
+Known limitations and non-obvious behaviors of Kinetica 7.2.x that affect
+diagnostic SQL generation, mutation planning, and result interpretation.
+If the agent is about to suggest any of the patterns below, these notes
+override the "obvious" choice.
+
+## Commands NOT Supported
+
+- **`ANALYZE TABLE`** — returns a syntax error. Kinetica does not maintain
+  cost-based optimizer statistics the way PostgreSQL or Oracle do; query
+  planning uses shard/column metadata already tracked by the storage
+  layer. Do NOT suggest `ANALYZE TABLE` as remediation for query
+  performance problems, and do NOT propose it via
+  `kinetica_execute_mutation_sql` — there is no equivalent "refresh table
+  stats" command to substitute.
+- **`ALTER TABLE ... SET SHARD KEY`** on existing columns — shard keys are
+  immutable once designated at table creation. To change a shard key, the
+  table must be dropped and recreated.
+
+## Missing System Tables in 7.2.x
+
+Querying either of these returns an `"Object not found"` error. Do NOT
+attempt them — use the replacement instead:
+
+- `ki_catalog.ki_tables` — does NOT exist. Use
+  `ki_catalog.ki_objects WHERE obj_kind = 'R'` to list tables (see
+  `knowledge/references/` for the full `obj_kind` enum).
+- `ki_catalog.ki_version` — does NOT exist. Get the version from
+  `kinetica_health_check` or `kinetica_get_system_properties`
+  (`version.*` keys). The version is also surfaced as `version` in the
+  session context at startup, so you usually don't need to query at
+  all.
+
+## `ki_catalog.ki_columns` — Correct Column Names
+
+The schema uses these names (not the "obvious" SQL-standard names):
+
+| Do NOT use         | Correct 7.2.x name                                                   |
+| ------------------ | -------------------------------------------------------------------- |
+| `data_type`        | `column_type_oid` (long; join to `ki_datatypes.oid` for type name)   |
+| `dict_encoding`    | `is_dict_encoded` (int flag, 0 or 1)                                 |
+| `compression_type` | `bytes_on_disk_compressed` / `bytes_on_disk_uncompressed` (two cols) |
+
+## Response Sentinel Values
+
+- **`/admin/verifydb`** returns `orphaned_tables_total_size: -1` on
+  healthy systems — `-1` means "check was not run", NOT "something is
+  wrong". Do NOT flag `-1` as a problem in diagnostic reports. A real
+  orphan count is a non-negative integer.
+
+## Endpoint Preconditions
+
+- **`/admin/rebalance`** requires 2+ worker ranks. Single-worker clusters
+  return `"Database must be offline"` — this is expected behavior, not a
+  bug, and means rebalance is simply not applicable. Do not suggest
+  rebalance on clusters with only rank 0 + one worker.
+- **`/show/table`** accepts only two-part names (`<schema>.<table>`).
+  Three-part names like `ki_home.ki_catalog.ki_objects` return a 400
+  error. Use `ki_catalog.ki_objects` (two parts).
+- **`/show/table`** with empty `table_name` returns schema-level
+  collections with an empty `sizes` array — NOT a list of tables with
+  sizes. For a real table listing with sizes, query
+  `ki_catalog.ki_objects` via SQL instead.
+- **`/admin/show/logs`** is not implemented on 7.2.x — returns 404
+  "Unknown URI". The `kinetica_get_logs` tool falls back to SQL against
+  `ki_catalog.ki_log`.
+
+## Default Resource Groups
+
+Every 7.2.x install ships with two groups that should not be flagged as
+anomalies:
+
+- `kinetica_system_resource_group` — priority 100 (system reserved)
+- `kinetica_default_resource_group` — priority 50 (default user group)
+
+`/show/resourcegroups` includes a `max_tier_priority` field per group.
+User-created groups sit between these defaults.

package/knowledge/templates/report.md

@@ -0,0 +1,57 @@
+# Kinetica Diagnostic Report
+
+| Field                             | Value                   |
+| --------------------------------- | ----------------------- |
+| **Investigation Date/Time (UTC)** | YYYY-MM-DD HH:MM:SS UTC |
+| **Kinetica Version**              | X.Y.Z.W                 |
+| **Investigation Duration**        | N minutes               |
+| **Tool Calls**                    | N                       |
+| **Rounds**                        | N                       |
+
+---
+
+## Summary
+
+[1-3 sentence executive summary. State whether the issue was identified and what it is.]
+
+---
+
+## Remediation
+
+[Numbered list of specific, actionable remediation steps tied to the identified root cause. Include both immediate manual actions and agent-assisted mutation steps.]
+
+---
+
+## Root Cause Analysis
+
+[Named root cause with supporting evidence. Commit to the most likely cause. If multiple hypotheses, rank by likelihood. No generic hedging.]
+
+---
+
+## Evidence Collected
+
+[Key findings only — NOT raw tool response dumps. Extract the relevant data points that support your conclusion. Reference which tool provided each finding.]
+
+---
+
+## Evidence Gaps
+
+[Any tool calls that failed or returned incomplete data. Include HTTP status codes where available, e.g., "Cluster status: unavailable (HTTP 503)". Write "None" if all tools responded successfully.]
+
+---
+
+## Mutations Applied
+
+| Timestamp | Tool      | Parameters  | Before | After | Approval        | Verified             |
+| --------- | --------- | ----------- | ------ | ----- | --------------- | -------------------- |
+| HH:MM:SS  | tool_name | param=value | old    | new   | APPROVED/DENIED | confirmed/failed/N/A |
+
+Write "None" if no mutations were proposed during this investigation.
+
+---
+
+## Post-Remediation Verification
+
+[Summary of Round 5 re-check results. What was confirmed changed. What still shows warning.
+Include specific metric comparisons: "GPU memory reduced from 95% to 78%".
+Write "Not applicable -- no mutations applied" if no mutations were approved.]

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@kinetica/admin-agent",
+  "version": "0.1.0",
+  "description": "Autonomous diagnostic agent for Kinetica databases",
+  "license": "Apache-2.0",
+  "author": "Kinetica",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineticadb/admin-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kineticadb/admin-agent/issues"
+  },
+  "homepage": "https://github.com/kineticadb/admin-agent#readme",
+  "keywords": [
+    "kinetica",
+    "database",
+    "diagnostics",
+    "agent",
+    "dba",
+    "ai-agent",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=20.20"
+  },
+  "files": [
+    "dist/",
+    "knowledge/",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "bin": {
+    "admin-agent": "./dist/admin-agent.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "chmod +x dist/admin-agent.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "dev": "tsx src/cli/index.ts",
+    "eval": "tsx src/evals/report-format.eval.ts",
+    "eval:report-format": "tsx src/evals/report-format.eval.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "~0.2.80",
+    "@inquirer/prompts": "^8.3.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.5.0",
+    "prettier": "^3.8.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.0.18"
+  }
+}