katt 0.0.6 → 0.0.8

package/.nvmrc

@@ -0,0 +1 @@
+24

package/README.md

@@ -9,6 +9,7 @@ Katt is a lightweight testing framework for running AI Evals, inspired by [Jest]
 
 - [Overview](#overview)
 - [API Documentation](#api-documentation)
+- [Articles](#articles)
 - [Hello World - Example](#hello-world---example)
 - [Main Features](#main-features)
 - [Usage](#usage)
@@ -34,6 +35,10 @@ Katt is designed to evaluate and validate the behavior of AI agents like **Claud
 
 For a complete list of features and usage examples, see [docs/api-documentation.md](https://github.com/raphaelpor/katt/blob/main/docs/api-documentation.md).
 
+## Articles
+
+- [Introducing Katt](https://github.com/raphaelpor/katt/blob/main/docs/articles/introduction-to-katt.md)
+
 ## Hello World - Example
 
 ```typescript
@@ -63,6 +68,7 @@ describe("Greeting agent", () => {
 - **Classification Matcher**: Built-in `toBeClassifiedAs()` matcher to grade a response against a target label on a 1-5 scale
 - **Concurrent Execution**: Runs eval files concurrently for faster test execution
 - **Model Selection**: Support for specifying custom AI models
+- **Runtime Selection**: Run prompts through GitHub Copilot (default) or Codex
 - **Configurable Timeouts**: Override prompt wait time per test or via `katt.json`
 
 ## Usage
@@ -86,7 +92,7 @@ expect(result).toContain("hello world");
 2. Run Katt from your project directory:
 
 ```bash
-katt
+npx katt
 ```
 
 ### Using promptFile
@@ -122,11 +128,14 @@ describe("Model selection", () => {
 });
 ```
 
-You can also set a default model for the project by adding a `katt.json` file in the project root:
+You can also set runtime defaults in `katt.json`.
+
+Copilot (default runtime):
 
 ```json
 {
-  "copilot": {
+  "agent": "gh-copilot",
+  "agentOptions": {
     "model": "gpt-5-mini"
   },
   "prompt": {
@@ -135,10 +144,29 @@ You can also set a default model for the project by adding a `katt.json` file in
 }
 ```
 
+Codex:
+
+```json
+{
+  "agent": "codex",
+  "agentOptions": {
+    "model": "gpt-5-codex",
+    "profile": "default",
+    "sandbox": "workspace-write"
+  },
+  "prompt": {
+    "timeoutMs": 240000
+  }
+}
+```
+
 When this file exists:
 
-- `prompt("...")` and `promptFile("...")` use `copilot.model` by default
-- `prompt("...", { model: "..." })` still overrides the config value
+- Supported agents are:
+  - `gh-copilot` (default when `agent` is missing or unsupported)
+  - `codex`
+- `prompt("...")` and `promptFile("...")` merge `agentOptions` with call-time options
+- `prompt("...", { model: "..." })` overrides the model from config
 - `prompt.timeoutMs` sets the default wait timeout for long-running prompts
 
 ## Development
@@ -196,8 +224,8 @@ katt/
 ## Requirements
 
 - Node.js
-- GitHub Copilot CLI installed (see [GitHub Copilot CLI installation docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/install-copilot-cli))
-- Access to AI models (e.g., OpenAI API key for Codex)
+- For `gh-copilot` runtime: access to GitHub Copilot with a logged-in user
+- For `codex` runtime: Codex CLI installed and authenticated (`codex login`)
 
 ## License
 

package/build-tests/__snapshots__/check1.snap.md

@@ -0,0 +1 @@
+heeey

package/build-tests/__snapshots__/check1__Hello_World__should_return_the_date_in_a_json_format.snap.md

@@ -0,0 +1 @@
+{ year: 2026 }

package/build-tests/__snapshots__/check1__root.snap.md

@@ -0,0 +1 @@
+heeey

package/build-tests/check1.eval.js

@@ -0,0 +1,19 @@
+import { describe, expect, it, prompt } from "katt";
+
+describe('Hello World', () => {
+    it('should return the date in a json format', async () => {
+        const currentData = new Date(Date.now());
+
+        const result = await prompt('Return the current year in the format "{ year: YYYY }"');
+        expect(result).toContain(`{ year: ${currentData.getFullYear()} }`);
+    });
+
+    it('should classify a response as helpful', async () => {
+        const response = await prompt('You are a helpful assistant. Give one short tip for learning JavaScript.');
+        await expect(response).toBeClassifiedAs('helpful', { threshold: 3 });
+    });
+});
+
+
+const result2 = await prompt('If you read this just say heeey');
+expect(result2.toLowerCase()).toMatchSnapshot();

package/build-tests/check2.eval.js

@@ -0,0 +1,15 @@
+import { describe, expect, it, prompt, promptFile } from "katt";
+
+describe('Working with files', () => {
+    it('It should load the file and compare', async () => {
+        const result = await promptFile('./customPrompt.md');
+        expect(result.toLowerCase()).toContain('hola');
+    });
+});
+
+describe('Working with prompt as expectation', () => {
+    it('It should be friendly', async () => {
+        const result = await prompt('You are a friendly assistant. If you read this, say "Hola"!', { model: 'gpt-5.2' });
+        expect(result).promptCheck('To be friendly, the response should contain a greeting.');
+    });
+});

package/build-tests/customPrompt.md

@@ -0,0 +1 @@
+If you read this, say "Hola"!