@valuya/telegram-bot-channel 0.2.0-beta.1 → 0.2.0

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 (4) hide show
  1. package/.env.example +6 -1
  2. package/README.md +49 -1
  3. package/dist/server.js +32 -9
  4. package/package.json +6 -6
package/.env.example CHANGED
@@ -22,6 +22,11 @@ TELEGRAM_CHANNEL_SOUL_NAME=Mentor
22
22
  TELEGRAM_CHANNEL_SOUL_LOCALE=de
23
23
  TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT=Du bist ein ruhiger, klarer Mentor und hilfst dem Nutzer, sein eigentliches Thema besser zu verstehen.
24
24
  TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON={"format":"json","replyKey":"mentor_reply","followUpQuestionKey":"deep_question","followUpQuestionsKey":"follow_up_questions","nextStepKey":"next_step","summaryKey":"conversation_summary","userProfileKey":"user_profile","rootPatternKey":"root_pattern"}
25
+ TELEGRAM_CHANNEL_SOUL_PROVIDER=openai
26
+ TELEGRAM_CHANNEL_SOUL_WEBHOOK_URL=
27
+ TELEGRAM_CHANNEL_SOUL_WEBHOOK_AUTH_TOKEN=
28
+ TELEGRAM_CHANNEL_SOUL_WEBHOOK_TIMEOUT_MS=30000
29
+ TELEGRAM_CHANNEL_SOUL_WEBHOOK_HEADERS_JSON=
25
30
 
26
31
  OPENAI_API_KEY=sk-...
27
- OPENAI_MODEL=gpt-4.1-mini
32
+ OPENAI_MODEL=gpt-5.2-chat-latest
package/README.md CHANGED
@@ -34,8 +34,10 @@ This package builds on `@valuya/telegram-channel-access`.
34
34
  - `TELEGRAM_CHANNEL_MODE=human`
35
35
  - or `TELEGRAM_CHANNEL_MODE=agent`
36
36
  4. If `agent`, set:
37
- - `OPENAI_API_KEY`
38
37
  - `TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT`
38
+ - and either:
39
+ - `OPENAI_API_KEY`
40
+ - or `TELEGRAM_CHANNEL_SOUL_PROVIDER=webhook|n8n|langchain|api` plus `TELEGRAM_CHANNEL_SOUL_WEBHOOK_URL`
39
41
  - optional `TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON`
40
42
  5. Start it from the package folder:
41
43
  - `pnpm start`
@@ -49,6 +51,52 @@ This package builds on `@valuya/telegram-channel-access`.
49
51
  - gated human Q&A channel
50
52
  - agent-moderated support channel
51
53
 
54
+ ## External AI Providers
55
+
56
+ Agent mode can run through:
57
+
58
+ - OpenAI directly
59
+ - `n8n`
60
+ - LangChain services
61
+ - any API-compatible orchestration service
62
+
63
+ Use:
64
+
65
+ - `TELEGRAM_CHANNEL_SOUL_PROVIDER=openai`
66
+ - or `TELEGRAM_CHANNEL_SOUL_PROVIDER=webhook`
67
+ - aliases also accepted:
68
+ - `n8n`
69
+ - `langchain`
70
+ - `api`
71
+
72
+ Webhook settings:
73
+
74
+ - `TELEGRAM_CHANNEL_SOUL_WEBHOOK_URL`
75
+ - `TELEGRAM_CHANNEL_SOUL_WEBHOOK_AUTH_TOKEN`
76
+ - `TELEGRAM_CHANNEL_SOUL_WEBHOOK_TIMEOUT_MS`
77
+ - `TELEGRAM_CHANNEL_SOUL_WEBHOOK_HEADERS_JSON`
78
+
79
+ See the shared contract in:
80
+ - [external-soul-runtime-webhook-contract.md](/home/colt/Software/valuya-guard/docs/external-soul-runtime-webhook-contract.md)
81
+
82
+ For a runnable local reference runtime:
83
+
84
+ ```bash
85
+ pnpm gated-channel:runtime-demo
86
+ ```
87
+
88
+ For `n8n`, use:
89
+ - [n8n-bot-channel-runtime-guide.md](/home/colt/Software/valuya-guard/docs/n8n-bot-channel-runtime-guide.md)
90
+
91
+ For LangChain-style runtimes, use:
92
+ - [langchain-bot-channel-runtime-guide.md](/home/colt/Software/valuya-guard/docs/langchain-bot-channel-runtime-guide.md)
93
+
94
+ For Python-first runtimes, use:
95
+ - [python-bot-channel-runtime-guide.md](/home/colt/Software/valuya-guard/docs/python-bot-channel-runtime-guide.md)
96
+
97
+ For a backend selection overview, use:
98
+ - [choose-bot-channel-runtime-backend.md](/home/colt/Software/valuya-guard/docs/choose-bot-channel-runtime-backend.md)
99
+
52
100
  ## Starter Template
53
101
 
54
102
  For the reusable rollout model, see:
package/dist/server.js CHANGED
@@ -1,12 +1,14 @@
1
1
  import { createServer } from "node:http";
2
- import { createConfiguredSoul, createOptionalOpenAISoulRuntime, normalizeChannelMode, } from "@valuya/bot-channel-bootstrap-core";
3
- import { createOpenAIResponsesRunner, getRequestPath, handleInternalJsonMessage, requiredEnv, } from "@valuya/bot-channel-server-core";
2
+ import { createConfiguredSoul, createOptionalOpenAISoulRuntime, createOptionalWebhookSoulRuntime, normalizeChannelMode, normalizeSoulProvider, parseJsonHeaders, } from "@valuya/bot-channel-bootstrap-core";
3
+ import { createOpenAIResponsesRunner, getRequestPath, handleInternalJsonMessage, loadEnvFile, requiredEnv, } from "@valuya/bot-channel-server-core";
4
4
  import { TelegramBotChannelApp } from "./app/TelegramBotChannelApp.js";
5
5
  import { GuardTelegramChannelLinkResolver } from "./linking/GuardTelegramChannelLinkResolver.js";
6
6
  import { FileSoulMemoryStore } from "./memory/FileSoulMemoryStore.js";
7
7
  import { SchemaDrivenSoulRuntime } from "./runtime/SchemaDrivenSoulRuntime.js";
8
8
  import { TelegramBotChannel } from "./runtime/TelegramBotChannel.js";
9
9
  import { createMentorSoulDefinition } from "./souls/createMentorSoulDefinition.js";
10
+ import { WebhookSoulRuntime } from "@valuya/bot-channel-core";
11
+ loadEnvFile();
10
12
  const PORT = Number(process.env.PORT || 8792);
11
13
  const HOST = process.env.HOST?.trim() || "0.0.0.0";
12
14
  const LINKS_FILE = requiredEnv("TELEGRAM_LINKS_FILE");
@@ -30,6 +32,11 @@ const CHANNEL_MODE = normalizeChannelMode({
30
32
  });
31
33
  const OPENAI_API_KEY = process.env.OPENAI_API_KEY?.trim() || "";
32
34
  const OPENAI_MODEL = process.env.OPENAI_MODEL?.trim() || "gpt-4.1-mini";
35
+ const SOUL_PROVIDER = normalizeSoulProvider(process.env.TELEGRAM_CHANNEL_SOUL_PROVIDER);
36
+ const SOUL_WEBHOOK_URL = process.env.TELEGRAM_CHANNEL_SOUL_WEBHOOK_URL?.trim() || "";
37
+ const SOUL_WEBHOOK_AUTH_TOKEN = process.env.TELEGRAM_CHANNEL_SOUL_WEBHOOK_AUTH_TOKEN?.trim() || "";
38
+ const SOUL_WEBHOOK_TIMEOUT_MS = Number(process.env.TELEGRAM_CHANNEL_SOUL_WEBHOOK_TIMEOUT_MS || "30000");
39
+ const SOUL_WEBHOOK_HEADERS_JSON = process.env.TELEGRAM_CHANNEL_SOUL_WEBHOOK_HEADERS_JSON?.trim() || "";
33
40
  const HUMAN_REPLY = process.env.TELEGRAM_CHANNEL_HUMAN_REPLY?.trim() || "";
34
41
  const INTERNAL_API_TOKEN = process.env.TELEGRAM_CHANNEL_INTERNAL_API_TOKEN?.trim() || "";
35
42
  const linkResolver = new GuardTelegramChannelLinkResolver({
@@ -49,6 +56,23 @@ const souls = CHANNEL_MODE.kind === "agent"
49
56
  responseSchemaJson: SOUL_RESPONSE_SCHEMA_JSON,
50
57
  })]
51
58
  : [];
59
+ const soulRuntime = SOUL_PROVIDER === "webhook"
60
+ ? createOptionalWebhookSoulRuntime({
61
+ mode: CHANNEL_MODE,
62
+ provider: SOUL_PROVIDER,
63
+ url: SOUL_WEBHOOK_URL,
64
+ authToken: SOUL_WEBHOOK_AUTH_TOKEN,
65
+ timeoutMs: SOUL_WEBHOOK_TIMEOUT_MS,
66
+ extraHeaders: parseJsonHeaders(SOUL_WEBHOOK_HEADERS_JSON),
67
+ createRuntime: (args) => new WebhookSoulRuntime(args),
68
+ })
69
+ : createOptionalOpenAISoulRuntime({
70
+ mode: CHANNEL_MODE,
71
+ apiKey: OPENAI_API_KEY,
72
+ model: OPENAI_MODEL,
73
+ createRunner: createOpenAICompletionRunner,
74
+ createRuntime: (args) => new SchemaDrivenSoulRuntime(args),
75
+ });
52
76
  const channel = new TelegramBotChannel({
53
77
  baseUrl: VALUYA_BASE,
54
78
  tenantToken: VALUYA_TENANT_TOKEN,
@@ -60,13 +84,7 @@ const channel = new TelegramBotChannel({
60
84
  mode: CHANNEL_MODE,
61
85
  souls,
62
86
  memoryStore: new FileSoulMemoryStore(SOUL_MEMORY_FILE),
63
- soulRuntime: createOptionalOpenAISoulRuntime({
64
- mode: CHANNEL_MODE,
65
- apiKey: OPENAI_API_KEY,
66
- model: OPENAI_MODEL,
67
- createRunner: createOpenAICompletionRunner,
68
- createRuntime: (args) => new SchemaDrivenSoulRuntime(args),
69
- }),
87
+ soulRuntime,
70
88
  humanReply: HUMAN_REPLY || undefined,
71
89
  linking: linkResolver,
72
90
  });
@@ -111,6 +129,11 @@ server.listen(PORT, HOST, () => {
111
129
  port: PORT,
112
130
  internalPath: "/internal/message",
113
131
  channelMode: CHANNEL_MODE.kind,
132
+ soulProvider: SOUL_PROVIDER,
133
+ soulRuntimePresent: soulRuntime ? true : false,
134
+ openaiConfigured: OPENAI_API_KEY ? true : false,
135
+ openaiModel: OPENAI_MODEL || null,
136
+ webhookConfigured: SOUL_WEBHOOK_URL ? true : false,
114
137
  resource: CHANNEL_RESOURCE || null,
115
138
  plan: CHANNEL_PLAN,
116
139
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@valuya/telegram-bot-channel",
3
- "version": "0.2.0-beta.1",
3
+ "version": "0.2.0",
4
4
  "description": "Gated Telegram channel example with human or soul-moderated runtime on top of Valuya Guard",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -20,11 +20,11 @@
20
20
  ".env.concierge.example"
21
21
  ],
22
22
  "dependencies": {
23
- "@valuya/bot-channel-app-core": "^0.2.0-beta.1",
24
- "@valuya/bot-channel-bootstrap-core": "^0.2.0-beta.1",
25
- "@valuya/bot-channel-core": "^0.2.0-beta.1",
26
- "@valuya/bot-channel-server-core": "^0.2.0-beta.1",
27
- "@valuya/telegram-channel-access": "^0.2.0-beta.1"
23
+ "@valuya/bot-channel-app-core": "^0.2.0",
24
+ "@valuya/bot-channel-bootstrap-core": "^0.2.0",
25
+ "@valuya/bot-channel-core": "^0.2.0",
26
+ "@valuya/bot-channel-server-core": "^0.2.0",
27
+ "@valuya/telegram-channel-access": "^0.2.0"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^25.0.10"