ak-claude 0.0.1 → 0.0.2

package/README.md

@@ -295,6 +295,110 @@ For `CodeAgent`, `stop()` also kills any currently running child process via SIG
 
 All classes extend `BaseClaude` and share these features (except `AgentQuery`, which wraps the Claude Agent SDK separately).
 
+### Raw SDK Client Access
+
+All classes expose the underlying SDK clients via the `clients` namespace for advanced use cases:
+
+```javascript
+import { Chat } from 'ak-claude';
+
+const chat = new Chat({ apiKey: process.env.ANTHROPIC_API_KEY });
+await chat.init();
+
+// Access raw SDK clients
+console.log(chat.clients.anthropic);  // @anthropic-ai/sdk client (or null if using Vertex)
+console.log(chat.clients.vertex);     // @anthropic-ai/vertex-sdk client (or null if using direct API)
+console.log(chat.clients.raw);        // Convenience pointer to whichever is active
+
+// Use raw client for SDK features not yet wrapped
+for await (const model of chat.clients.raw.beta.models.list()) {
+  console.log(model.id, model.display_name);
+}
+
+// Access message batches API
+const batch = await chat.clients.anthropic.messages.batches.create({
+  requests: [
+    { custom_id: 'req1', params: { model: 'claude-haiku-4-5-20251001', max_tokens: 1024, messages: [...] } },
+    { custom_id: 'req2', params: { model: 'claude-haiku-4-5-20251001', max_tokens: 1024, messages: [...] } }
+  ]
+});
+
+// Count tokens directly
+const tokenCount = await chat.clients.raw.messages.countTokens({
+  model: 'claude-sonnet-4-6',
+  messages: chat.history
+});
+```
+
+**When to use:**
+- Access new SDK features before they're wrapped
+- Beta APIs and experimental features
+- Low-level operations (message batches, etc.)
+- SDK-specific functionality
+
+**Common patterns:**
+
+```javascript
+// Check which client is active
+console.log('Using Anthropic:', chat.clients.anthropic !== null);
+console.log('Using Vertex:', chat.clients.vertex !== null);
+
+// Advanced streaming
+const stream = chat.clients.raw.messages.stream({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello' }]
+});
+stream.on('text', (delta) => process.stdout.write(delta));
+await stream.finalMessage();
+```
+
+The original `client` property remains for backward compatibility (`client === clients.raw`).
+
+### Model Discovery
+
+List and inspect available Claude models (direct API only, not Vertex AI):
+
+```javascript
+import { Chat } from 'ak-claude';
+
+const chat = new Chat({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+// List all available models
+for await (const model of chat.listModels()) {
+  console.log(model.id);          // "claude-sonnet-4-6"
+  console.log(model.display_name); // "Claude 4.6 Sonnet"
+  console.log(model.created_at);   // RFC 3339 datetime
+}
+
+// Get info about a specific model
+const modelInfo = await chat.getModel('claude-sonnet-4-6');
+console.log(modelInfo);
+
+// Find newest model
+let newestModel = null;
+let newestDate = new Date(0);
+for await (const model of chat.listModels()) {
+  const createdAt = new Date(model.created_at);
+  if (createdAt > newestDate) {
+    newestDate = createdAt;
+    newestModel = model;
+  }
+}
+
+// Check if a model exists
+async function modelExists(modelId) {
+  try {
+    await chat.getModel(modelId);
+    return true;
+  } catch (err) {
+    return err.status !== 404;
+  }
+}
+```
+
+**Note:** These helpers only work with direct Anthropic API authentication, not Vertex AI. You can also access the models API via the raw client: `chat.clients.raw.beta.models.list()`.
+
 ### Authentication
 
 ```javascript
@@ -308,6 +412,8 @@ new Chat({ vertexai: true, vertexProjectId: 'my-project', vertexRegion: 'us-cent
 new Chat({ apiKey: 'your-key' }); // or ANTHROPIC_API_KEY / CLAUDE_API_KEY env var
 ```
 
+**Note:** Vertex AI doesn't allow both `temperature` and `topP` to be specified together. When using Vertex AI, the module automatically uses only `temperature` if both are set, and `topP` is not sent to the API. The default for Vertex AI is `temperature: 0.7` (no `topP`).
+
 ### Token Estimation
 
 Uses Claude's `countTokens` API for exact input token counts before sending.

package/base.js

@@ -82,7 +82,8 @@ class BaseClaude {
 		// ── Generation Config ──
 		this.maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
 		this.temperature = options.temperature ?? 0.7;
-		this.topP = options.topP ?? 0.95;
+		// Vertex AI doesn't allow both temperature and topP - only set topP default for direct API
+		this.topP = options.topP ?? (this.vertexai ? undefined : 0.95);
 		this.topK = options.topK ?? undefined;
 
 		// ── Extended Thinking ──
@@ -109,11 +110,22 @@ class BaseClaude {
 		// _ensureClient() is called at the start of every API method.
 		this.client = null;
 		this._clientReady = false;
+
+		// ── Clients Namespace (for raw SDK access) ──
+		// Exposes the underlying SDK clients for advanced use cases
+		this.clients = {
+			anthropic: null,  // @anthropic-ai/sdk client (direct API)
+			vertex: null,     // @anthropic-ai/vertex-sdk client
+			raw: null         // Convenience pointer to whichever is active
+		};
+
 		if (!this.vertexai) {
 			this.client = new Anthropic({
 				apiKey: this.apiKey,
 				maxRetries: this.maxRetries
 			});
+			this.clients.anthropic = this.client;
+			this.clients.raw = this.client;
 			this._clientReady = true;
 		}
 
@@ -174,6 +186,8 @@ class BaseClaude {
 				}
 				return superBuildRequest.call(this, options, extra);
 			};
+			this.clients.vertex = this.client;
+			this.clients.raw = this.client;
 			this._clientReady = true;
 			log.debug(`${this.constructor.name}: Vertex AI client created (project=${this.vertexProjectId}, region=${this.vertexRegion})`);
 		}
@@ -282,8 +296,15 @@ class BaseClaude {
 			params.thinking = this.thinking;
 			// When thinking is enabled, temperature must be 1 and top_p/top_k are not supported
 		} else {
-			if (this.temperature !== undefined) params.temperature = this.temperature;
-			if (this.topP !== undefined) params.top_p = this.topP;
+			// Vertex AI doesn't allow both temperature and topP
+			if (this.vertexai && this.temperature !== undefined && this.topP !== undefined) {
+				// Prefer temperature, skip topP for Vertex AI
+				params.temperature = this.temperature;
+				log.debug('Vertex AI: Using temperature only (topP ignored)');
+			} else {
+				if (this.temperature !== undefined) params.temperature = this.temperature;
+				if (this.topP !== undefined) params.top_p = this.topP;
+			}
 		}
 
 		const response = await this.client.messages.create(params);
@@ -328,8 +349,15 @@ class BaseClaude {
 		if (this.thinking) {
 			params.thinking = this.thinking;
 		} else {
-			if (this.temperature !== undefined) params.temperature = this.temperature;
-			if (this.topP !== undefined) params.top_p = this.topP;
+			// Vertex AI doesn't allow both temperature and topP
+			if (this.vertexai && this.temperature !== undefined && this.topP !== undefined) {
+				// Prefer temperature, skip topP for Vertex AI
+				params.temperature = this.temperature;
+				log.debug('Vertex AI: Using temperature only (topP ignored)');
+			} else {
+				if (this.temperature !== undefined) params.temperature = this.temperature;
+				if (this.topP !== undefined) params.top_p = this.topP;
+			}
 		}
 
 		const stream = this.client.messages.stream(params);
@@ -563,6 +591,53 @@ class BaseClaude {
 		};
 	}
 
+	// ── Model Management ─────────────────────────────────────────────────────
+
+	/**
+	 * Lists all available models from the Anthropic API.
+	 * Provides model IDs, display names, and creation dates.
+	 * Returns an async iterable that automatically fetches more pages as needed.
+	 *
+	 * NOTE: Only available with direct Anthropic API access (not Vertex AI).
+	 * @returns {AsyncIterable<Object>} AsyncIterable of model objects
+	 * @throws {Error} If using Vertex AI authentication
+	 * @example
+	 * const chat = new Chat({ apiKey: 'your-key' });
+	 * for await (const model of chat.listModels()) {
+	 *   console.log(model.id, model.display_name);
+	 * }
+	 */
+	async *listModels() {
+		if (this.vertexai) {
+			throw new Error('listModels() is not available with Vertex AI. Use direct Anthropic API authentication instead.');
+		}
+		await this._ensureClient();
+		const pageIterator = this.client.beta.models.list();
+		for await (const model of pageIterator) {
+			yield model;
+		}
+	}
+
+	/**
+	 * Retrieves detailed information about a specific model.
+	 *
+	 * NOTE: Only available with direct Anthropic API access (not Vertex AI).
+	 * @param {string} modelId - The model ID (e.g., 'claude-sonnet-4-6')
+	 * @returns {Promise<Object>} The model details
+	 * @throws {Error} If using Vertex AI authentication
+	 * @example
+	 * const chat = new Chat({ apiKey: 'your-key' });
+	 * const modelInfo = await chat.getModel('claude-sonnet-4-6');
+	 * console.log(modelInfo);
+	 */
+	async getModel(modelId) {
+		if (this.vertexai) {
+			throw new Error('getModel() is not available with Vertex AI. Use direct Anthropic API authentication instead.');
+		}
+		await this._ensureClient();
+		return await this.client.beta.models.retrieve(modelId);
+	}
+
 	// ── Application-Level Retry ──────────────────────────────────────────────
 
 	/**

package/index.cjs

@@ -342,7 +342,7 @@ var BaseClaude = class {
     }
     this.maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
     this.temperature = options.temperature ?? 0.7;
-    this.topP = options.topP ?? 0.95;
+    this.topP = options.topP ?? (this.vertexai ? void 0 : 0.95);
     this.topK = options.topK ?? void 0;
     this.thinking = options.thinking ?? null;
     this.cacheSystemPrompt = options.cacheSystemPrompt ?? false;
@@ -353,11 +353,21 @@ var BaseClaude = class {
     this._configureLogLevel(options.logLevel);
     this.client = null;
     this._clientReady = false;
+    this.clients = {
+      anthropic: null,
+      // @anthropic-ai/sdk client (direct API)
+      vertex: null,
+      // @anthropic-ai/vertex-sdk client
+      raw: null
+      // Convenience pointer to whichever is active
+    };
     if (!this.vertexai) {
       this.client = new import_sdk.default({
         apiKey: this.apiKey,
         maxRetries: this.maxRetries
       });
+      this.clients.anthropic = this.client;
+      this.clients.raw = this.client;
       this._clientReady = true;
     }
     this.history = [];
@@ -408,6 +418,8 @@ var BaseClaude = class {
         }
         return superBuildRequest.call(this, options, extra);
       };
+      this.clients.vertex = this.client;
+      this.clients.raw = this.client;
       this._clientReady = true;
       logger_default.debug(`${this.constructor.name}: Vertex AI client created (project=${this.vertexProjectId}, region=${this.vertexRegion})`);
     }
@@ -495,8 +507,13 @@ var BaseClaude = class {
     if (this.thinking) {
       params.thinking = this.thinking;
     } else {
-      if (this.temperature !== void 0) params.temperature = this.temperature;
-      if (this.topP !== void 0) params.top_p = this.topP;
+      if (this.vertexai && this.temperature !== void 0 && this.topP !== void 0) {
+        params.temperature = this.temperature;
+        logger_default.debug("Vertex AI: Using temperature only (topP ignored)");
+      } else {
+        if (this.temperature !== void 0) params.temperature = this.temperature;
+        if (this.topP !== void 0) params.top_p = this.topP;
+      }
     }
     const response = await this.client.messages.create(params);
     this.history.push({ role: "assistant", content: response.content });
@@ -528,8 +545,13 @@ var BaseClaude = class {
     if (this.thinking) {
       params.thinking = this.thinking;
     } else {
-      if (this.temperature !== void 0) params.temperature = this.temperature;
-      if (this.topP !== void 0) params.top_p = this.topP;
+      if (this.vertexai && this.temperature !== void 0 && this.topP !== void 0) {
+        params.temperature = this.temperature;
+        logger_default.debug("Vertex AI: Using temperature only (topP ignored)");
+      } else {
+        if (this.temperature !== void 0) params.temperature = this.temperature;
+        if (this.topP !== void 0) params.top_p = this.topP;
+      }
     }
     const stream = this.client.messages.stream(params);
     return stream;
@@ -724,6 +746,50 @@ ${contextText}
       note: "Cost is for input tokens only; output cost depends on response length"
     };
   }
+  // ── Model Management ─────────────────────────────────────────────────────
+  /**
+   * Lists all available models from the Anthropic API.
+   * Provides model IDs, display names, and creation dates.
+   * Returns an async iterable that automatically fetches more pages as needed.
+   *
+   * NOTE: Only available with direct Anthropic API access (not Vertex AI).
+   * @returns {AsyncIterable<Object>} AsyncIterable of model objects
+   * @throws {Error} If using Vertex AI authentication
+   * @example
+   * const chat = new Chat({ apiKey: 'your-key' });
+   * for await (const model of chat.listModels()) {
+   *   console.log(model.id, model.display_name);
+   * }
+   */
+  async *listModels() {
+    if (this.vertexai) {
+      throw new Error("listModels() is not available with Vertex AI. Use direct Anthropic API authentication instead.");
+    }
+    await this._ensureClient();
+    const pageIterator = this.client.beta.models.list();
+    for await (const model of pageIterator) {
+      yield model;
+    }
+  }
+  /**
+   * Retrieves detailed information about a specific model.
+   *
+   * NOTE: Only available with direct Anthropic API access (not Vertex AI).
+   * @param {string} modelId - The model ID (e.g., 'claude-sonnet-4-6')
+   * @returns {Promise<Object>} The model details
+   * @throws {Error} If using Vertex AI authentication
+   * @example
+   * const chat = new Chat({ apiKey: 'your-key' });
+   * const modelInfo = await chat.getModel('claude-sonnet-4-6');
+   * console.log(modelInfo);
+   */
+  async getModel(modelId) {
+    if (this.vertexai) {
+      throw new Error("getModel() is not available with Vertex AI. Use direct Anthropic API authentication instead.");
+    }
+    await this._ensureClient();
+    return await this.client.beta.models.retrieve(modelId);
+  }
   // ── Application-Level Retry ──────────────────────────────────────────────
   /**
    * Wraps an async function with retry logic.

package/package.json

@@ -2,7 +2,7 @@
 	"name": "ak-claude",
 	"author": "ak@mixpanel.com",
 	"description": "AK's Claude AI Helper for doing... everything",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"main": "index.js",
 	"files": [
 		"index.js",

package/types.d.ts

@@ -402,6 +402,15 @@ export declare class BaseClaude {
   modelName: string;
   systemPrompt: string | null | false;
   client: any;
+  /** Raw SDK clients namespace for advanced use cases */
+  clients: {
+    /** @anthropic-ai/sdk client (null when using Vertex AI) */
+    anthropic: any | null;
+    /** @anthropic-ai/vertex-sdk client (null when using direct API) */
+    vertex: any | null;
+    /** Convenience pointer to whichever client is active */
+    raw: any;
+  };
   history: any[];
   lastResponseMetadata: ResponseMetadata | null;
   exampleCount: number;
@@ -427,6 +436,8 @@ export declare class BaseClaude {
     estimatedInputCost: number;
     note: string;
   }>;
+  listModels(): AsyncGenerator<any, void, unknown>;
+  getModel(modelId: string): Promise<any>;
 }
 
 export declare class Transformer extends BaseClaude {