kortyx 0.9.3 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +183 -6
  3. package/dist/index.d.ts +1 -1
  4. package/dist/index.js +2 -0
  5. package/dist/index.js.map +1 -1
  6. package/package.json +14 -9
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.10.1](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.10.0...kortyx-v0.10.1) (2026-05-22)
4
+
5
+
6
+ ### Dependencies
7
+
8
+ * The following workspace dependencies were updated
9
+ * dependencies
10
+ * @kortyx/agent bumped to 0.11.1
11
+ * @kortyx/core bumped to 0.5.3
12
+ * @kortyx/hooks bumped to 0.12.1
13
+ * @kortyx/runtime bumped to 0.9.4
14
+
15
+ ## [0.10.0](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.9.3...kortyx-v0.10.0) (2026-05-20)
16
+
17
+
18
+ ### Features
19
+
20
+ * **chat:** add request context plumbing ([7210a6f](https://github.com/kortyx-io/kortyx/commit/7210a6f9275728628e1862bd7b0f200112bd9b08))
21
+
22
+
23
+ ### Dependencies
24
+
25
+ * The following workspace dependencies were updated
26
+ * dependencies
27
+ * @kortyx/agent bumped to 0.11.0
28
+ * @kortyx/core bumped to 0.5.2
29
+ * @kortyx/hooks bumped to 0.12.0
30
+ * @kortyx/runtime bumped to 0.9.3
31
+ * @kortyx/stream bumped to 0.7.0
32
+ * @kortyx/utils bumped to 0.2.6
33
+
3
34
  ## [0.9.3](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.9.2...kortyx-v0.9.3) (2026-05-04)
4
35
 
5
36
 
package/README.md CHANGED
@@ -1,20 +1,197 @@
1
1
  # kortyx
2
2
 
3
- The “batteries included” Kortyx package that aggregates the core building blocks.
3
+ [![npm version](https://img.shields.io/npm/v/kortyx.svg)](https://www.npmjs.com/package/kortyx)
4
+ [![CI](https://github.com/kortyx-io/kortyx/actions/workflows/ci.yml/badge.svg)](https://github.com/kortyx-io/kortyx/actions/workflows/ci.yml)
5
+ [![License](https://img.shields.io/npm/l/kortyx.svg)](https://github.com/kortyx-io/kortyx/blob/main/LICENSE)
6
+ [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
7
+ [![Node](https://img.shields.io/badge/Node.js-%3E%3D22-339933.svg)](https://github.com/kortyx-io/kortyx/blob/main/package.json)
8
+
9
+ **Kortyx is a TypeScript framework for building production AI agents with explicit workflows, provider-agnostic models, typed hooks, streaming, interrupts, and runtime persistence.**
10
+
11
+ Use `kortyx` as the main package. It re-exports the public server/runtime APIs from the supporting `@kortyx/*` packages so application code can stay focused on workflows, nodes, providers, and UI transport.
4
12
 
5
13
  ## Install
6
14
 
7
15
  ```bash
8
- npm install kortyx
16
+ pnpm add kortyx @kortyx/google @kortyx/react
17
+ ```
18
+
19
+ ```bash
20
+ npm install kortyx @kortyx/google @kortyx/react
21
+ ```
22
+
23
+ ## Quickstart
24
+
25
+ Create a workflow:
26
+
27
+ ```ts
28
+ // src/workflows/general-chat.workflow.ts
29
+ import { defineWorkflow } from "kortyx";
30
+ import { chatNode } from "@/nodes/chat.node";
31
+
32
+ export const generalChatWorkflow = defineWorkflow({
33
+ id: "general-chat",
34
+ version: "1.0.0",
35
+ description: "Single-node chat workflow.",
36
+ nodes: {
37
+ chat: {
38
+ run: chatNode,
39
+ params: {
40
+ temperature: 0.3,
41
+ },
42
+ },
43
+ },
44
+ edges: [
45
+ ["__start__", "chat"],
46
+ ["chat", "__end__"],
47
+ ],
48
+ });
49
+ ```
50
+
51
+ Add a server-side node:
52
+
53
+ ```ts
54
+ // src/nodes/chat.node.ts
55
+ import { google } from "@kortyx/google";
56
+ import { useReason } from "kortyx";
57
+
58
+ type ChatParams = {
59
+ temperature?: number;
60
+ };
61
+
62
+ export const chatNode = async ({
63
+ input,
64
+ params,
65
+ }: {
66
+ input: unknown;
67
+ params: ChatParams;
68
+ }) => {
69
+ const result = await useReason({
70
+ id: "chat",
71
+ model: google("gemini-2.5-flash"),
72
+ system: "You are a concise assistant.",
73
+ input: String(input ?? ""),
74
+ temperature: params.temperature ?? 0.3,
75
+ stream: true,
76
+ emit: true,
77
+ });
78
+
79
+ return {
80
+ data: { text: result.text },
81
+ };
82
+ };
9
83
  ```
10
84
 
85
+ Wire the agent:
86
+
87
+ ```ts
88
+ // src/lib/agent.ts
89
+ import { createAgent } from "kortyx";
90
+ import { generalChatWorkflow } from "@/workflows/general-chat.workflow";
91
+
92
+ export const agent = createAgent({
93
+ workflows: [generalChatWorkflow],
94
+ defaultWorkflowId: "general-chat",
95
+ });
96
+ ```
97
+
98
+ Expose it through a Next.js API route:
99
+
100
+ ```ts
101
+ import { createChatRouteHandler } from "kortyx";
102
+ import { agent } from "@/lib/agent";
103
+
104
+ export const runtime = "nodejs";
105
+ export const dynamic = "force-dynamic";
106
+
107
+ const handleChat = createChatRouteHandler({ agent });
108
+
109
+ export async function POST(request: Request): Promise<Response> {
110
+ return handleChat(request);
111
+ }
112
+ ```
113
+
114
+ Consume the stream from React:
115
+
116
+ ```tsx
117
+ "use client";
118
+
119
+ import { createRouteChatTransport, useChat } from "@kortyx/react";
120
+
121
+ export function Chat() {
122
+ const chat = useChat({
123
+ transport: createRouteChatTransport({ endpoint: "/api/chat" }),
124
+ });
125
+
126
+ return (
127
+ <form
128
+ onSubmit={(event) => {
129
+ event.preventDefault();
130
+ const form = new FormData(event.currentTarget);
131
+ chat.send(String(form.get("message") ?? ""));
132
+ event.currentTarget.reset();
133
+ }}
134
+ >
135
+ {chat.messages.map((message) => (
136
+ <p key={message.id}>{message.content}</p>
137
+ ))}
138
+ {chat.streamContentPieces.map((piece) =>
139
+ piece.type === "text" ? (
140
+ <span key={piece.id}>{piece.content}</span>
141
+ ) : null,
142
+ )}
143
+ <input name="message" />
144
+ <button type="submit" disabled={chat.isStreaming}>
145
+ Send
146
+ </button>
147
+ </form>
148
+ );
149
+ }
150
+ ```
151
+
152
+ Set a provider key and run your app:
153
+
154
+ ```bash
155
+ GOOGLE_API_KEY=your_key_here pnpm dev
156
+ ```
157
+
158
+ ## API Groups
159
+
160
+ | Area | Exports |
161
+ | --- | --- |
162
+ | Agent | `createAgent`, `createChatRouteHandler`, `streamChatFromRoute` |
163
+ | Workflows | `defineWorkflow`, `loadWorkflow`, `validateWorkflow` |
164
+ | Hooks | `useReason`, `useInterrupt`, `useStructuredData`, `useNodeState`, `useWorkflowState`, `useRuntimeContext` |
165
+ | Runtime | workflow registries, node registry, in-memory/Redis framework adapters |
166
+ | Providers | provider contracts and registry helpers from `@kortyx/providers` |
167
+ | Streams | SSE helpers, stream readers, collectors, structured reducers |
168
+
169
+ ## Provider Packages
170
+
171
+ Install only the provider integrations your app needs.
172
+
173
+ | Provider | Package | Factory | Default environment variable |
174
+ | --- | --- | --- | --- |
175
+ | Google Gemini | `@kortyx/google` | `google(...)` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
176
+ | OpenAI | `@kortyx/openai` | `openai(...)` | `OPENAI_API_KEY` |
177
+ | Anthropic | `@kortyx/anthropic` | `anthropic(...)` | `ANTHROPIC_API_KEY` |
178
+ | DeepSeek | `@kortyx/deepseek` | `deepseek(...)` | `DEEPSEEK_API_KEY` |
179
+ | Groq | `@kortyx/groq` | `groq(...)` | `GROQ_API_KEY` |
180
+ | Mistral | `@kortyx/mistral` | `mistral(...)` | `MISTRAL_API_KEY` |
181
+
11
182
  ## Documentation
12
183
 
13
- This repo is under active development. For the latest package list and links, see the monorepo README:
184
+ - [Monorepo](https://github.com/kortyx-io/kortyx)
185
+ - [Documentation](https://kortyx.io/docs)
186
+ - [Package overview](https://kortyx.io/docs/reference/package-overview)
187
+ - [Quickstart: Next.js API Route](https://kortyx.io/docs/getting-started/quickstart-nextjs)
188
+ - [Runtime persistence](https://kortyx.io/docs/production/persistence)
189
+ - [Provider guide](https://kortyx.io/docs/kortyx-providers/choose-a-provider)
14
190
 
15
- - `README.md`
191
+ ## Studio
16
192
 
17
- ## License
193
+ Kortyx Studio is on the way for cost tracking, logs, observability, prompt tracking, and operational review.
18
194
 
19
- Apache-2.0
195
+ ## License
20
196
 
197
+ Apache-2.0. See [LICENSE](https://github.com/kortyx-io/kortyx/blob/main/LICENSE).
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { Agent, AgentProcessOptions, ChatRequestBody, CreateAgentArgs, StreamChatFromRouteArgs, createAgent, createChatRouteHandler, handleChatRequestBody, parseChatRequestBody, streamChatFromRoute } from '@kortyx/agent';
2
2
  export { GraphState, NodeConfig, NodeContext, NodeFn, NodeHandler, NodeResult, RuntimeEnvelope, WorkflowDefinition, WorkflowId, defineWorkflow, loadWorkflow, validateWorkflow } from '@kortyx/core';
3
- export { UseInterruptArgs, UseReasonArgs, UseReasonResult, UseStructuredDataArgs, useInterrupt, useNodeState, useReason, useStructuredData, useWorkflowState } from '@kortyx/hooks';
3
+ export { UseInterruptArgs, UseReasonArgs, UseReasonResult, UseStructuredDataArgs, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflowState } from '@kortyx/hooks';
4
4
  export * from '@kortyx/providers';
5
5
  export { WorkflowRegistry, clearRegisteredNodes, createFileWorkflowRegistry, createFrameworkAdapterFromEnv, createInMemoryFrameworkAdapter, createInMemoryWorkflowRegistry, createRedisFrameworkAdapter, getRegisteredNode, listRegisteredNodes, registerNode } from '@kortyx/runtime';
6
6
  export { BufferedStreamResult, ConsumeStreamHandlers, StreamChunk, StructuredDataChunk, StructuredStreamAccumulator, StructuredStreamState, applyStructuredChunk, collectBufferedStream, collectStream, consumeStream, createStreamResponse, createStructuredStreamAccumulator, readStream, reduceStructuredChunks, summarizeStreamChunks, toSSE } from '@kortyx/stream';
package/dist/index.js CHANGED
@@ -49,6 +49,7 @@ __export(index_exports, {
49
49
  useInterrupt: () => import_hooks.useInterrupt,
50
50
  useNodeState: () => import_hooks.useNodeState,
51
51
  useReason: () => import_hooks.useReason,
52
+ useRuntimeContext: () => import_hooks.useRuntimeContext,
52
53
  useStructuredData: () => import_hooks.useStructuredData,
53
54
  useWorkflowState: () => import_hooks.useWorkflowState,
54
55
  validateWorkflow: () => import_core.validateWorkflow
@@ -91,6 +92,7 @@ var import_stream = require("@kortyx/stream");
91
92
  useInterrupt,
92
93
  useNodeState,
93
94
  useReason,
95
+ useRuntimeContext,
94
96
  useStructuredData,
95
97
  useWorkflowState,
96
98
  validateWorkflow,
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// release-test: 2026-01-22\n// Public DX surface for the Kortyx framework.\n\nexport type {\n Agent,\n AgentProcessOptions,\n ChatRequestBody,\n CreateAgentArgs,\n StreamChatFromRouteArgs,\n} from \"@kortyx/agent\";\nexport {\n createAgent,\n createChatRouteHandler,\n handleChatRequestBody,\n parseChatRequestBody,\n streamChatFromRoute,\n} from \"@kortyx/agent\";\nexport type {\n GraphState,\n NodeConfig,\n NodeContext,\n NodeFn,\n NodeHandler,\n NodeResult,\n RuntimeEnvelope,\n WorkflowDefinition,\n WorkflowId,\n} from \"@kortyx/core\";\nexport { defineWorkflow, loadWorkflow, validateWorkflow } from \"@kortyx/core\";\nexport type {\n UseInterruptArgs,\n UseReasonArgs,\n UseReasonResult,\n UseStructuredDataArgs,\n} from \"@kortyx/hooks\";\nexport {\n useInterrupt,\n useNodeState,\n useReason,\n useStructuredData,\n useWorkflowState,\n} from \"@kortyx/hooks\";\nexport * from \"@kortyx/providers\";\nexport type { WorkflowRegistry } from \"@kortyx/runtime\";\nexport {\n clearRegisteredNodes,\n createFileWorkflowRegistry,\n createFrameworkAdapterFromEnv,\n createInMemoryFrameworkAdapter,\n createInMemoryWorkflowRegistry,\n createRedisFrameworkAdapter,\n getRegisteredNode,\n listRegisteredNodes,\n registerNode,\n} from \"@kortyx/runtime\";\nexport type {\n BufferedStreamResult,\n ConsumeStreamHandlers,\n StreamChunk,\n StructuredDataChunk,\n StructuredStreamAccumulator,\n StructuredStreamState,\n} from \"@kortyx/stream\";\nexport {\n applyStructuredChunk,\n collectBufferedStream,\n collectStream,\n consumeStream,\n createStreamResponse,\n createStructuredStreamAccumulator,\n readStream,\n reduceStructuredChunks,\n summarizeStreamChunks,\n toSSE,\n} from \"@kortyx/stream\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,mBAMO;AAYP,kBAA+D;AAO/D,mBAMO;AACP,0BAAc,8BA1Cd;AA4CA,qBAUO;AASP,oBAWO;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// release-test: 2026-01-22\n// Public DX surface for the Kortyx framework.\n\nexport type {\n Agent,\n AgentProcessOptions,\n ChatRequestBody,\n CreateAgentArgs,\n StreamChatFromRouteArgs,\n} from \"@kortyx/agent\";\nexport {\n createAgent,\n createChatRouteHandler,\n handleChatRequestBody,\n parseChatRequestBody,\n streamChatFromRoute,\n} from \"@kortyx/agent\";\nexport type {\n GraphState,\n NodeConfig,\n NodeContext,\n NodeFn,\n NodeHandler,\n NodeResult,\n RuntimeEnvelope,\n WorkflowDefinition,\n WorkflowId,\n} from \"@kortyx/core\";\nexport { defineWorkflow, loadWorkflow, validateWorkflow } from \"@kortyx/core\";\nexport type {\n UseInterruptArgs,\n UseReasonArgs,\n UseReasonResult,\n UseStructuredDataArgs,\n} from \"@kortyx/hooks\";\nexport {\n useInterrupt,\n useNodeState,\n useReason,\n useRuntimeContext,\n useStructuredData,\n useWorkflowState,\n} from \"@kortyx/hooks\";\nexport * from \"@kortyx/providers\";\nexport type { WorkflowRegistry } from \"@kortyx/runtime\";\nexport {\n clearRegisteredNodes,\n createFileWorkflowRegistry,\n createFrameworkAdapterFromEnv,\n createInMemoryFrameworkAdapter,\n createInMemoryWorkflowRegistry,\n createRedisFrameworkAdapter,\n getRegisteredNode,\n listRegisteredNodes,\n registerNode,\n} from \"@kortyx/runtime\";\nexport type {\n BufferedStreamResult,\n ConsumeStreamHandlers,\n StreamChunk,\n StructuredDataChunk,\n StructuredStreamAccumulator,\n StructuredStreamState,\n} from \"@kortyx/stream\";\nexport {\n applyStructuredChunk,\n collectBufferedStream,\n collectStream,\n consumeStream,\n createStreamResponse,\n createStructuredStreamAccumulator,\n readStream,\n reduceStructuredChunks,\n summarizeStreamChunks,\n toSSE,\n} from \"@kortyx/stream\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,mBAMO;AAYP,kBAA+D;AAO/D,mBAOO;AACP,0BAAc,8BA3Cd;AA6CA,qBAUO;AASP,oBAWO;","names":[]}
package/package.json CHANGED
@@ -1,14 +1,19 @@
1
1
  {
2
2
  "name": "kortyx",
3
- "version": "0.9.3",
3
+ "version": "0.10.1",
4
4
  "private": false,
5
- "description": "The batteries-included Kortyx package that aggregates the core building blocks.",
5
+ "description": "TypeScript framework for production AI agents with explicit workflows, provider-agnostic models, streaming, interrupts, and runtime persistence.",
6
6
  "keywords": [
7
7
  "ai",
8
8
  "agent",
9
9
  "agents",
10
+ "llm",
10
11
  "orchestration",
11
12
  "framework",
13
+ "workflow",
14
+ "streaming",
15
+ "typescript",
16
+ "human-in-the-loop",
12
17
  "kortyx"
13
18
  ],
14
19
  "license": "Apache-2.0",
@@ -35,13 +40,13 @@
35
40
  "CHANGELOG.md"
36
41
  ],
37
42
  "dependencies": {
38
- "@kortyx/agent": "0.10.3",
39
- "@kortyx/hooks": "0.11.0",
43
+ "@kortyx/agent": "0.11.1",
44
+ "@kortyx/core": "0.5.3",
45
+ "@kortyx/hooks": "0.12.1",
46
+ "@kortyx/runtime": "0.9.4",
40
47
  "@kortyx/providers": "0.4.0",
41
- "@kortyx/runtime": "0.9.2",
42
- "@kortyx/core": "0.5.1",
43
- "@kortyx/stream": "0.6.1",
44
- "@kortyx/utils": "0.2.5"
48
+ "@kortyx/stream": "0.7.0",
49
+ "@kortyx/utils": "0.2.6"
45
50
  },
46
51
  "devDependencies": {
47
52
  "turbo": "2.6.1",
@@ -63,6 +68,6 @@
63
68
  "dev": "tsc --watch",
64
69
  "lint": "biome check src",
65
70
  "test": "pnpm -s type-check",
66
- "type-check": "tsc --noEmit"
71
+ "type-check": "tsc --noEmit -p tsconfig.test.json"
67
72
  }
68
73
  }