@kat-ai/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,212 +1,80 @@
 # @kat-ai/cli
 
-Knowledge Base Tools CLI - A unified command-line interface for managing Pinecone knowledge bases.
+CLI for scaffolding KAT apps, generating manifests, introspecting Pinecone Assistants, and running eval workflows.
 
-## Installation
+## Install
 
-### From npm (when published)
+Run once with `npx`:
 
 ```bash
-npm install -g @kat-ai/cli
-```
-
-Introspection + Eval baseline package set:
-
-```bash
-npm install @kat-ai/sdk@0.1.0 @kat-ai/eval@0.1.0 @kat-ai/cli@0.1.0
-```
-
-### From source
-
-```bash
-# Clone the repository
-git clone https://github.com/pinecone-io/kat.git
-cd kat
-
-# Install dependencies
-pnpm install
-
-# Build the CLI
-pnpm cli:build
-
-# Link for global usage
-cd packages/cli
-npm link
-```
-
-## Usage
-
-### Interactive Mode
-
-Run without arguments to enter interactive mode:
-
-```bash
-kat
-```
-
-### Commands
-
-#### Ingest Data
-
-Ingest CSV data into Pinecone assistants with topic extraction:
-
-```bash
-# Interactive mode
-kat ingest -i
-
-# Direct mode
-kat ingest --output pinecone
-kat ingest --output local --dir ./data/ingested
-kat ingest --output both --dry-run
+npx @kat-ai/cli --help
 ```
 
-Options:
-- `-o, --output <mode>` - Output mode: pinecone, local, or both (default: pinecone)
-- `-d, --dir <path>` - Local output directory for ingested files
-- `--dry-run` - Preview changes without making them
-- `-i, --interactive` - Run in interactive mode
-
-#### Compose Manifest
-
-Build KB manifests with AI assistance:
+Install globally if you use it often:
 
 ```bash
-# Interactive mode
-kat compose -i
-
-# Direct mode
-kat compose --kb-id my_kb --domain support --description "Support KB"
-kat compose --kb-id my_kb --source ./data/faq.csv --storage both
+npm install -g @kat-ai/cli
+kat --help
 ```
 
-Options:
-- `--kb-id <id>` - KB identifier
-- `--domain <domain>` - Domain name
-- `--description <desc>` - Short description
-- `--assistant <name>` - Pinecone assistant name
-- `--source <path>` - Path to source CSV data
-- `-s, --storage <mode>` - Storage mode: local, pinecone, or both
-- `--dry-run` - Preview without saving
-
-#### Introspect Assistant
+The published package is `@kat-ai/cli`, but the installed binary is `kat`.
 
-Generate manifest from existing Pinecone assistant:
+## Environment
 
-```bash
-# Interactive mode
-kat introspect -i
+Most commands expect these environment variables, either in your shell or in `.env.local`:
 
-# Direct mode
-kat introspect --assistant my-assistant --kb-id my_kb
-kat introspect --assistant my-assistant --storage both --verbose
+```env
+OPENAI_API_KEY=sk-...
+PINECONE_API_KEY=...
 ```
 
-Options:
-- `-a, --assistant <name>` - Pinecone assistant name
-- `--kb-id <id>` - KB identifier
-- `--domain <domain>` - Domain name
-- `-s, --storage <mode>` - Storage mode
-- `--verbose` - Show detailed Q&A during introspection
-- `--dry-run` - Preview without saving
+## Quick Start
 
-#### Validate Data
-
-Validate CSV data against KB definitions:
+Generate a new app:
 
 ```bash
-# Interactive mode
-kat validate -i
-
-# Direct mode
-kat validate
-kat validate --path ./data
-kat validate --json
+npx @kat-ai/cli generate -i
 ```
 
-Options:
-- `-p, --path <path>` - Path to CSV file or directory
-- `--json` - Output results as JSON
-
-#### Test Topics
-
-Test topic extraction on files:
+Generate manifests from an existing Pinecone Assistant:
 
 ```bash
-# Interactive mode
-kat topics -i
-
-# Direct mode
-kat topics ./data/document.txt
-kat topics ./data/*.csv --mode slm --top-n 10
-kat topics ./docs --mode hybrid --verbose
+npx @kat-ai/cli introspect --assistant my-assistant --verbose
 ```
 
-Options:
-- `-m, --mode <mode>` - Extraction mode: classic (TF-IDF), slm (LLM), or hybrid
-- `-n, --top-n <n>` - Number of topics per document (default: 5)
-- `--verbose` - Show document previews
-- `--json` - Output as JSON
-
-#### Sync Manifests
-
-Sync manifests between local files and Pinecone:
+Build manifests interactively:
 
 ```bash
-# Interactive mode
-kat sync -i
-
-# Direct mode
-kat sync --direction toLocal
-kat sync --direction toPinecone
-kat sync --direction both --dry-run
+npx @kat-ai/cli compose -i
 ```
 
-Options:
-- `-d, --direction <dir>` - Sync direction: toLocal, toPinecone, or both
-- `--dry-run` - Preview changes without making them
-
-### Global Options
-
-- `-v, --version` - Display version number
-- `--no-color` - Disable colored output
-- `--verbose` - Enable verbose output
-- `-h, --help` - Display help
-
-## Environment Variables
-
-Create a `.env.local` file with the following variables:
-
-```env
-PINECONE_API_KEY=your-pinecone-api-key
-OPENAI_API_KEY=your-openai-api-key
-```
-
-The CLI will automatically look for `.env.local` in the current directory and parent directories.
-
-## Development
-
-### Build
+Run the eval baseline:
 
 ```bash
-pnpm cli:build
+npx @kat-ai/cli eval \
+  --assistant my-assistant \
+  --endpoint http://localhost:3000/api/chat \
+  --baseline
 ```
 
-### Development Mode (watch)
-
-```bash
-pnpm cli:dev
-```
+## Commands
 
-### Run locally
+- `generate`: scaffold a new KAT application
+- `introspect`: derive manifests from an existing Pinecone Assistant
+- `compose`: build manifests interactively
+- `sync`: sync local manifests and Pinecone state
+- `validate`: validate data and manifest inputs
+- `ingest`: optional CSV ingestion workflow
+- `topics`: inspect topic extraction behavior
+- `eval`: run introspection, retrieval, and agent evaluation
 
-```bash
-# After building
-node packages/cli/dist/index.js
+## Related Packages
 
-# Or with tsx (development)
-pnpm cli:legacy
-```
+- `@kat-ai/sdk`: core runtime and server-side integration helpers
+- `@kat-ai/react`: React components for citations and follow-up options
+- `@kat-ai/eval`: programmatic evaluation APIs used by `kat eval`
 
-## License
+## Docs
 
-MIT
+- Repository: [github.com/pinecone-io/KAT](https://github.com/pinecone-io/KAT)
+- CLI docs: [docs-site/docs/cli](https://github.com/pinecone-io/KAT/tree/main/docs-site/docs/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kat-ai/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for KAT ingestion, composition, introspection, and evaluation workflows",
   "type": "module",
   "bin": {
@@ -29,8 +29,8 @@
     "dotenv": "^17.2.3",
     "natural": "^8.0.1",
     "zod": "^3.23.0",
-    "@kat-ai/sdk": "0.1.0",
-    "@kat-ai/eval": "0.1.0"
+    "@kat-ai/eval": "0.1.1",
+    "@kat-ai/sdk": "0.1.1"
   },
   "devDependencies": {
     "@types/natural": "^5.1.5",