From 8f2ff1c88918c23385f87937f2cf9748f66ab6e6 Mon Sep 17 00:00:00 2001 From: Duy Nguyen Date: Sat, 10 Oct 2026 17:22:50 +0700 Subject: [PATCH 1/2] docs: add decision layer (Jev) guide Explain the three opt-in uses of TypeSafe Jev (memory admission, busy-agent intent classification, semantic trace evaluation), their default-off modes, third-party egress and redaction, instance-wide scope, fail-open limits and the dewee reflex commands, in English and Vietnamese. Link the page from the tracing and CLI references. Co-Authored-By: Claude Opus 5.5 --- .../docs/en/concepts/decision-layer.md | 150 ++++++++++++++++++ src/content/docs/en/concepts/tracing.md | 5 +- src/content/docs/en/runtime/cli.md | 4 +- .../docs/vi/concepts/decision-layer.md | 150 ++++++++++++++++++ src/content/docs/vi/concepts/tracing.md | 5 +- src/content/docs/vi/runtime/cli.md | 4 +- 6 files changed, 310 insertions(+), 8 deletions(-) create mode 100644 src/content/docs/en/concepts/decision-layer.md create mode 100644 src/content/docs/vi/concepts/decision-layer.md diff --git a/src/content/docs/en/concepts/decision-layer.md b/src/content/docs/en/concepts/decision-layer.md new file mode 100644 index 0000000..2458718 --- /dev/null +++ b/src/content/docs/en/concepts/decision-layer.md @@ -0,0 +1,150 @@ +--- +title: Decision layer (Jev by TypeSafe) +description: How dewee asks TypeSafe Jev small, typed questions to gate memory writes, read busy-agent intent and label traces. Each use stays off until an operator opts in. +section: concepts +order: 12 +updated: 2026-10-10 +--- + +The decision layer lets dewee ask a small, fast model narrow, typed questions instead of paying a full LLM call for them. The model is **Jev**, a "System One" model from TypeSafe. Each question has a fixed shape, such as "is this worth keeping?" or "which of these four intents is this message?", and Jev answers with a choice or a score plus a confidence. + +dewee uses Jev in three places. Each one is **off by default** and is switched on separately, so turning one on never turns on another: + +| Use | What Jev decides | Config switch | +|---|---|---| +| Memory admission | Whether content is worth writing to memory or the knowledge graph, and which recalled memories are worth adding to a turn | `reflex_enabled` plus `reflex_mode` and per-seam modes | +| Busy-agent intent | What a message means when it arrives while the agent is still working | `intent_classify_mode` | +| Semantic trace evaluation (beta) | Labels on finished traces, such as whether the task succeeded | `trace_semantic_enabled` | + +Jev does not route models or tools, write answers or moderate what users say. It only answers the questions listed on this page. + +In the console's settings the feature appears as **Decision layer: Jev by TypeSafe**. It is configured once for the whole instance by the operator. + +> [!WARNING] +> When any of these uses is on, dewee sends content to a third party, `api.typesafe.ai`. Credentials, email addresses and phone numbers are redacted before each request, but the rest of the memory, message or trace text leaves your server. TypeSafe's zero data retention is available on its enterprise tier only; the early-access tier keeps data under TypeSafe's own terms. Read them before you turn this on for content you cannot disclose. + +## Setup and scope + +All three uses share one TypeSafe API key, one endpoint and one pinned model, `jev-1.13.0`. The moving `jev-latest` alias is never used, because thresholds are tuned per model version. Store the key without echoing it: + +```bash +read -rs KEY && printf '%s' "$KEY" | dewee reflex config set-key +dewee reflex status +``` + +The configuration is **instance-wide**. Settings resolve from the tenant to the master tenant, so one write at master scope applies to every tenant that has not set its own value. `dewee reflex status` reports `scope: instance` and `key_present`, so you can see what is in effect. A mode other than `off` does nothing until a key is stored. + +## Memory admission + +Several background jobs turn conversations and documents into memory: channel batches, knowledge-graph extraction, dreaming (memory consolidation), episodic session summaries and the memory flush at the end of a turn. Each of these is a **seam** where Jev can be asked, before the expensive LLM call, whether the content is worth keeping at all. A sixth seam, `retrieval`, works on the read side: it decides which recalled memories are worth adding to the current turn. + +### Modes + +| Mode | Behaviour | +|---|---| +| `off` (default) | No request to TypeSafe and no span. dewee behaves exactly as if the feature did not exist. | +| `shadow` | Jev is asked and the answer is traced, but it never changes what happens. Use this to observe before you trust it. | +| `gate` | Jev can veto the call when it is confident the content is worthless. For `retrieval`, `gate` means it filters and ranks the recalled memories. | + +A veto never loses work silently. Each seam has a deterministic fallback: a flush still writes memory, an episodic summary is still written from a plain summary, dreaming sets the gate aside after 3 vetoes in a row, and `retrieval` injects the normal results. Knowledge-graph extraction is the exception: a vetoed chunk gets no graph edges and is not retried. An operator who asks for extraction directly through the API is never gated. + +`shadow` does not change answers but does add latency on seams that run inside a turn, so the memory flush and retrieval seams sample shadow evaluations at 20% and 25% by default. + +### Turning it on + +`reflex_enabled` plus a stored key is the master switch for all memory-admission traffic. `reflex_mode` sets the default mode for the five write seams. The `retrieval` seam never inherits it: you turn it on with its own per-seam mode. + +```bash +dewee reflex config set --mode shadow # write seams observe (also sets reflex_enabled) +dewee reflex config set --seam-mode kg_chunk=gate # one seam vetoes +dewee reflex config set --seam-mode retrieval=shadow # read side observes +dewee reflex config set --mode off # write seams off +dewee reflex config set --disable # stop all memory-admission traffic +``` + +`reflex_mode=off` stops only the write seams. To stop every memory-admission request at once, clear `reflex_enabled` with `--disable`. Rollback is a single config write; nothing is migrated and no stored state needs cleaning up. + +### Read-side admission + +With `retrieval` on, one batched request per turn scores each recalled memory for usefulness. Admitted memories are ranked and trimmed to a token budget, and when every candidate is rejected no memory section is added at all. Admission leans towards keeping memories: a rejection needs a confident low score, and a low-confidence answer admits the memory. + +| Key | Default | Meaning | +|---|---|---| +| `reflex_seam_mode_retrieval` | `off` | `off`, `shadow` or `gate` | +| `reflex_read_timeout_ms` | `1500` | Deadline per evaluation, on the user-visible path | +| `reflex_retrieval_max_candidates` | `10` | Candidates sent per turn | +| `reflex_retrieval_max_tokens` | `200` | Largest injected memory section | +| `reflex_retrieval_admit_threshold` | `0.5` | Usefulness a memory needs to be admitted | +| `reflex_retrieval_min_confidence` | `0.5` | Confidence needed before a memory can be rejected | + +Run `retrieval` in `shadow` before `gate` on real traffic. The `reflex.decision` span records the counts and scores but never the memory text. + +## Busy-agent intent + +When a message arrives for an agent that is already working, dewee has to decide what it means before it can act: + +| Intent | What dewee does | +|---|---| +| `status_query` | Replies with progress and drops the message | +| `cancel` | Stops the running work | +| `steer` | Adds the message to the running loop | +| `new_task` | Queues the message as a separate run | + +The decision runs in three steps. A deterministic fast path matches obvious messages such as `stop`, `thôi`, `取消` or `?` with no network call; those never reach Jev. Ambiguous messages go to Jev when the mode allows it. Anything Jev cannot answer confidently goes to the generative LLM classifier dewee already used. + +| Mode | Behaviour | +|---|---| +| `off` (default) | Fast path plus the generative classifier. No request to TypeSafe and no span. | +| `shadow` | The generative classifier decides. Jev is also asked and its choice is recorded for comparison. | +| `active` | A Jev answer at or above the confidence floor is used. Below it, or on any failure, the generative classifier decides. | + +| Key | Default | Meaning | +|---|---|---| +| `intent_classify_mode` | `off` | `off`, `shadow` or `active` | +| `intent_classify_confidence_threshold` | `0.75` | Confidence floor for using a Jev answer | +| `intent_classify_confidence_threshold.` | instance floor | Per-language floor, such as `.vi` | +| `intent_classify_timeout_ms` | `1500` | Deadline per evaluation, at most 5000 | + +```bash +dewee reflex config set --intent-mode shadow +dewee reflex config set --intent-confidence 0.8 --intent-confidence-by-locale vi=0.8 +dewee reflex config set --intent-mode active +``` + +This switch is independent of memory admission: turning on intent classification sends only the incoming message, never memory content. Every failure, from a missing key to a timeout, falls back to the generative classifier with a recorded reason. If that classifier also fails, the message is treated as `new_task` and queued, never dropped. + +Each decision made while the mode is on writes one `intent.decision` span showing which classifier decided, the confidence, any fallback reason and, in shadow mode, whether Jev agreed. The message text is never stored. Agreement with the generative classifier is not accuracy, so judge `active` against a human-labelled sample. + +## Semantic trace evaluation + +Semantic evaluation is in beta and off until `trace_semantic_enabled` is set and a key is stored. Jev reads a bounded, redacted summary of a finished trace and labels it: task outcome, tool use, retrieval quality, efficiency, whether a human should review it and the likely failure mode. You can sample traces, or always evaluate failed, delegated, multi-tool or retrieval traces. + +The labels are **diagnostics only**. They add filters to `dewee traces list`, such as `--semantic-decision`, and never change an agent's behaviour, prompt, tools or trace status. A timeout records a failed evaluation and never blocks the agent. `dewee traces semantic config get` shows whether evaluation is on and why. See [Tracing and observability](/docs/concepts/tracing). + +## Limits and safety + +All three uses share one request budget and one circuit breaker per process: + +- `reflex_budget_rpm` (default 600) caps outbound requests per minute, counting each retry. When the budget runs out, requests are skipped and dewee carries on without Jev. +- After 5 consecutive failures the breaker opens for 30 seconds. An open breaker can only make dewee more permissive: nothing is vetoed and intent falls back to the generative classifier. +- `400`, `401` and `403` errors do not trip the breaker. They mean a bad key or question set and show up in `dewee reflex status` as `misconfigured`. +- The budget, breaker and counters are per process. With several gateway replicas, each replica has its own. + +Every path fails open. If TypeSafe is slow, down or unreachable, dewee behaves as it would with the decision layer off. + +## Commands + +| Command | Use it to | +|---|---| +| `dewee reflex status` | See the key, scope, per-seam mode and sampling, intent settings, breaker, budget and counters. Add `--json` for scripts. | +| `dewee reflex config set` | Change modes, sampling, thresholds and timeouts, or `set-key` to store the key | +| `dewee reflex test --set --state-file ` | Ask one seam's questions about a sample and see the answer | +| `dewee reflex eval --labels [--sweep]` | Score thresholds against a human-labelled sample | + +Thresholds ship as conservative starting values, not calibrated ones. Use `dewee reflex eval` with labels written by a person, not by the model, before you move a seam from `shadow` to `gate`. + +## Related + +- [Memory and knowledge vault](/docs/concepts/memory-and-knowledge): the memory jobs that the admission seams sit in front of. +- [Tracing and observability](/docs/concepts/tracing): the `reflex.decision` and `intent.decision` spans, and semantic evaluation filters. +- [CLI reference](/docs/runtime/cli): every `dewee reflex` command. diff --git a/src/content/docs/en/concepts/tracing.md b/src/content/docs/en/concepts/tracing.md index 7e7fb5b..ec75049 100644 --- a/src/content/docs/en/concepts/tracing.md +++ b/src/content/docs/en/concepts/tracing.md @@ -3,7 +3,7 @@ title: Tracing and observability description: What dewee records for every agent run, how long traces are kept, how cost and usage are totalled, and how to read traces from the console, CLI, API or OTel. section: concepts order: 10 -updated: 2026-09-25 +updated: 2026-10-10 --- Every agent run in dewee leaves a trace: a record of what the agent was asked, which models and tools it called, how long each step took, what it cost and how it ended. Traces are the first place to look when an answer is wrong, slow or expensive. They are written in the background, so recording them does not slow a run down. @@ -85,7 +85,7 @@ dewee traces timeline dewee --server https://dewee.example.com --token traces get -o json ``` -**Semantic evaluation** is in beta and off by default. When an operator turns it on and adds a TypeSafe API key, finished traces are sent to that external classifier, with credentials and personal data redacted, and labelled with signals such as whether the task succeeded. The labels become extra `dewee traces list` filters, such as `--semantic-decision`, and never change how an agent runs. `dewee traces semantic config get` shows whether it is on and why. +**Semantic evaluation** is in beta and off by default. When an operator turns it on and adds a TypeSafe API key, finished traces are sent to that external classifier, with credentials and personal data redacted, and labelled with signals such as whether the task succeeded. The labels become extra `dewee traces list` filters, such as `--semantic-decision`, and never change how an agent runs. `dewee traces semantic config get` shows whether it is on and why. The classifier is Jev, the same model the [decision layer](/docs/concepts/decision-layer) uses. ## Exporting to OpenTelemetry @@ -108,4 +108,5 @@ Spans are exported in batches of up to 100, every 5 seconds. The exporter is imp - [Agent loop](/docs/concepts/agent-loop): the steps each span records. - [Agent teams and delegation](/docs/concepts/agent-teams): following a request across agents. - [Workflows](/docs/concepts/workflows): workflow runs and their node spans. +- [Decision layer](/docs/concepts/decision-layer): the `reflex.decision` and `intent.decision` spans, and semantic evaluation. - [CLI reference](/docs/runtime/cli): all `dewee traces` and `dewee usage` commands. diff --git a/src/content/docs/en/runtime/cli.md b/src/content/docs/en/runtime/cli.md index 850ea56..8defae3 100644 --- a/src/content/docs/en/runtime/cli.md +++ b/src/content/docs/en/runtime/cli.md @@ -3,7 +3,7 @@ title: CLI reference description: "The dewee command line: global flags, how it finds the gateway and your key, output formats, and every command group for agents, skills, workflows and more." section: runtime order: 2 -updated: 2026-09-25 +updated: 2026-10-10 --- The same `dewee` binary that runs the gateway is also its command-line client. Most commands talk to a running gateway over HTTP or WebSocket, locally or remotely, so an operator can script almost everything the console does. A few maintenance commands work on the database directly and are meant for the host. @@ -99,7 +99,7 @@ dewee agent chat --name support-bot --message "Summarise today's open tickets" | `dewee cron` | `list`, `get`, `create`, `update`, `toggle`, `run`, `runs`, `status`, `delete` | | `dewee workflows` | `list`, `show`, `create`, `validate`, `apply`, `export`, `publish`, `rollback`, `enable`, `disable`, `trigger`, `delete`, `node-types`; `runs` to list, show, tail, cancel or retry runs | | `dewee heartbeat` | `get`, `set`, `toggle`, `test`, `logs`, `targets` | -| `dewee reflex` | `status`, `config`, `test`, `eval` | +| `dewee reflex` | `status`, `config`, `test`, `eval`; see [Decision layer](/docs/concepts/decision-layer) | Workflows can be kept as files and applied from CI: diff --git a/src/content/docs/vi/concepts/decision-layer.md b/src/content/docs/vi/concepts/decision-layer.md new file mode 100644 index 0000000..ad42ae0 --- /dev/null +++ b/src/content/docs/vi/concepts/decision-layer.md @@ -0,0 +1,150 @@ +--- +title: Lớp quyết định (Jev by TypeSafe) +description: Cách dewee hỏi TypeSafe Jev những câu hỏi nhỏ, có kiểu rõ ràng để chặn ghi bộ nhớ, phân loại ý định khi agent đang bận và gắn nhãn trace. Mọi thứ đều tắt sẵn. +section: concepts +order: 12 +updated: 2026-10-10 +--- + +Lớp quyết định cho phép dewee hỏi một model nhỏ và nhanh những câu hỏi hẹp, có kiểu rõ ràng, thay vì tốn cả một lần gọi LLM cho chúng. Model này là **Jev**, một model "System One" của TypeSafe. Mỗi câu hỏi có khuôn cố định, chẳng hạn "nội dung này có đáng giữ không?" hay "tin nhắn này thuộc ý định nào trong bốn ý định?", và Jev trả lời bằng một lựa chọn hoặc một điểm số kèm độ tin cậy. + +dewee dùng Jev ở ba chỗ. Cả ba đều **tắt mặc định** và được bật riêng, nên bật chỗ này không bao giờ kéo theo chỗ khác: + +| Mục đích | Jev quyết định điều gì | Khoá cấu hình | +|---|---|---| +| Kiểm duyệt ghi bộ nhớ | Nội dung có đáng ghi vào bộ nhớ hay knowledge graph không, và ký ức nào đáng đưa vào lượt hiện tại | `reflex_enabled` cùng `reflex_mode` và mode theo từng seam | +| Ý định khi agent đang bận | Một tin nhắn mang ý nghĩa gì khi nó đến lúc agent vẫn đang làm việc | `intent_classify_mode` | +| Đánh giá ngữ nghĩa trace (beta) | Nhãn cho các trace đã xong, chẳng hạn tác vụ có thành công không | `trace_semantic_enabled` | + +Jev không chọn model hay tool, không viết câu trả lời và không kiểm duyệt nội dung người dùng gửi. Nó chỉ trả lời những câu hỏi được nêu trong trang này. + +Trong phần cài đặt của console, tính năng này hiện với tên **Lớp quyết định: Jev by TypeSafe**. Người vận hành cấu hình nó một lần cho toàn bộ hệ thống. + +> [!WARNING] +> Khi bất kỳ tính năng nào ở đây được bật, dewee gửi nội dung tới một bên thứ ba là `api.typesafe.ai`. Thông tin xác thực, địa chỉ email và số điện thoại được che trước mỗi yêu cầu, nhưng phần còn lại của bộ nhớ, tin nhắn hay trace vẫn rời khỏi máy chủ của bạn. Chế độ không lưu dữ liệu (zero data retention) của TypeSafe chỉ có ở gói enterprise; gói early access lưu dữ liệu theo điều khoản riêng của TypeSafe. Hãy đọc kỹ các điều khoản đó trước khi bật cho nội dung bạn không được phép tiết lộ. + +## Thiết lập và phạm vi + +Cả ba mục đích dùng chung một API key của TypeSafe, một endpoint và một model được ghim là `jev-1.13.0`. Alias `jev-latest` không bao giờ được dùng, vì ngưỡng được tinh chỉnh theo từng phiên bản model. Lưu key mà không in nó ra màn hình: + +```bash +read -rs KEY && printf '%s' "$KEY" | dewee reflex config set-key +dewee reflex status +``` + +Cấu hình áp dụng cho **toàn bộ hệ thống**. Giá trị được đọc từ tenant rồi tới master tenant, nên một lần ghi ở phạm vi master áp dụng cho mọi tenant chưa tự đặt giá trị riêng. `dewee reflex status` báo `scope: instance` và `key_present` để bạn thấy cấu hình nào đang có hiệu lực. Mọi mode khác `off` đều không làm gì cho tới khi có key. + +## Kiểm duyệt ghi bộ nhớ + +Một số tác vụ nền biến hội thoại và tài liệu thành bộ nhớ: gom tin nhắn theo kênh, trích xuất knowledge graph, dreaming (hợp nhất bộ nhớ), tóm tắt phiên episodic và memory flush ở cuối mỗi lượt. Mỗi tác vụ là một **seam**, nơi dewee có thể hỏi Jev trước khi gọi LLM tốn kém rằng nội dung có đáng giữ hay không. Seam thứ sáu, `retrieval`, hoạt động ở phía đọc: nó quyết định những ký ức đã truy xuất nào đáng đưa vào lượt hiện tại. + +### Các mode + +| Mode | Hành vi | +|---|---| +| `off` (mặc định) | Không gửi yêu cầu tới TypeSafe và không ghi span. dewee chạy y như khi chưa có tính năng này. | +| `shadow` | Jev được hỏi và câu trả lời được ghi vào trace, nhưng không bao giờ thay đổi kết quả. Dùng mode này để quan sát trước khi tin tưởng. | +| `gate` | Jev có thể chặn lần gọi khi chắc chắn nội dung không có giá trị. Với `retrieval`, `gate` nghĩa là lọc và xếp hạng các ký ức được truy xuất. | + +Một lần chặn không bao giờ âm thầm làm mất việc. Mỗi seam có một đường dự phòng xác định: memory flush vẫn ghi bộ nhớ, tóm tắt episodic vẫn được ghi bằng bản tóm tắt đơn giản, dreaming bỏ qua cổng chặn sau 3 lần bị chặn liên tiếp, còn `retrieval` đưa vào kết quả như bình thường. Ngoại lệ là trích xuất knowledge graph: một đoạn bị chặn sẽ không có cạnh nào trong graph và không được thử lại. Khi người vận hành gọi trích xuất trực tiếp qua API, yêu cầu đó không bao giờ bị chặn. + +`shadow` không đổi câu trả lời nhưng có tăng độ trễ ở các seam chạy bên trong một lượt, vì vậy seam memory flush và `retrieval` mặc định chỉ lấy mẫu 20% và 25% số lần đánh giá ở mode shadow. + +### Bật tính năng + +`reflex_enabled` cùng một key đã lưu là công tắc tổng cho mọi yêu cầu kiểm duyệt bộ nhớ. `reflex_mode` đặt mode mặc định cho năm seam ghi. Seam `retrieval` không bao giờ kế thừa giá trị này: bạn bật nó bằng mode riêng của seam. + +```bash +dewee reflex config set --mode shadow # các seam ghi quan sát (đồng thời bật reflex_enabled) +dewee reflex config set --seam-mode kg_chunk=gate # một seam được phép chặn +dewee reflex config set --seam-mode retrieval=shadow # phía đọc quan sát +dewee reflex config set --mode off # tắt các seam ghi +dewee reflex config set --disable # dừng mọi yêu cầu kiểm duyệt bộ nhớ +``` + +`reflex_mode=off` chỉ dừng các seam ghi. Để dừng mọi yêu cầu kiểm duyệt bộ nhớ cùng lúc, hãy tắt `reflex_enabled` bằng `--disable`. Hoàn tác chỉ cần một lần ghi cấu hình; không có migration nào và không có dữ liệu nào cần dọn. + +### Kiểm duyệt phía đọc + +Khi bật `retrieval`, mỗi lượt gửi một yêu cầu gộp để chấm điểm mức hữu ích của từng ký ức được truy xuất. Các ký ức được chấp nhận sẽ được xếp hạng và cắt theo ngân sách token; nếu mọi ứng viên đều bị loại thì không có phần bộ nhớ nào được thêm vào. Cơ chế này nghiêng về phía giữ lại: muốn loại một ký ức phải có điểm thấp với độ tin cậy cao, còn câu trả lời có độ tin cậy thấp thì ký ức vẫn được giữ. + +| Khoá | Mặc định | Ý nghĩa | +|---|---|---| +| `reflex_seam_mode_retrieval` | `off` | `off`, `shadow` hoặc `gate` | +| `reflex_read_timeout_ms` | `1500` | Thời hạn cho mỗi lần đánh giá, trên đường người dùng chờ | +| `reflex_retrieval_max_candidates` | `10` | Số ứng viên gửi đi mỗi lượt | +| `reflex_retrieval_max_tokens` | `200` | Kích thước tối đa của phần bộ nhớ được thêm vào | +| `reflex_retrieval_admit_threshold` | `0.5` | Mức hữu ích tối thiểu để một ký ức được chấp nhận | +| `reflex_retrieval_min_confidence` | `0.5` | Độ tin cậy tối thiểu trước khi một ký ức có thể bị loại | + +Hãy chạy `retrieval` ở `shadow` trước khi chuyển sang `gate` trên lưu lượng thật. Span `reflex.decision` ghi lại số lượng và điểm số, nhưng không bao giờ ghi nội dung ký ức. + +## Ý định khi agent đang bận + +Khi một tin nhắn đến lúc agent vẫn đang làm việc, dewee phải hiểu tin nhắn đó muốn gì trước khi xử lý: + +| Ý định | dewee làm gì | +|---|---| +| `status_query` | Trả lời tiến độ và bỏ qua tin nhắn | +| `cancel` | Dừng công việc đang chạy | +| `steer` | Đưa tin nhắn vào vòng lặp đang chạy | +| `new_task` | Xếp tin nhắn vào hàng đợi thành một lượt chạy riêng | + +Quyết định đi qua ba bước. Đường nhanh xác định nhận ra các tin nhắn rõ ràng như `stop`, `thôi`, `取消` hay `?` mà không cần gọi mạng; những tin nhắn này không bao giờ tới Jev. Tin nhắn mơ hồ được gửi tới Jev nếu mode cho phép. Những gì Jev không trả lời được với đủ độ tin cậy sẽ chuyển sang bộ phân loại LLM sinh văn bản mà dewee vẫn dùng từ trước. + +| Mode | Hành vi | +|---|---| +| `off` (mặc định) | Đường nhanh cộng bộ phân loại sinh văn bản. Không gửi yêu cầu tới TypeSafe và không ghi span. | +| `shadow` | Bộ phân loại sinh văn bản quyết định. Jev cũng được hỏi và lựa chọn của nó được ghi lại để so sánh. | +| `active` | Câu trả lời của Jev đạt ngưỡng tin cậy trở lên sẽ được dùng. Dưới ngưỡng, hoặc khi có bất kỳ lỗi nào, bộ phân loại sinh văn bản quyết định. | + +| Khoá | Mặc định | Ý nghĩa | +|---|---|---| +| `intent_classify_mode` | `off` | `off`, `shadow` hoặc `active` | +| `intent_classify_confidence_threshold` | `0.75` | Ngưỡng tin cậy để dùng câu trả lời của Jev | +| `intent_classify_confidence_threshold.` | ngưỡng của hệ thống | Ngưỡng riêng theo ngôn ngữ, chẳng hạn `.vi` | +| `intent_classify_timeout_ms` | `1500` | Thời hạn cho mỗi lần đánh giá, tối đa 5000 | + +```bash +dewee reflex config set --intent-mode shadow +dewee reflex config set --intent-confidence 0.8 --intent-confidence-by-locale vi=0.8 +dewee reflex config set --intent-mode active +``` + +Công tắc này độc lập với kiểm duyệt bộ nhớ: bật phân loại ý định chỉ gửi tin nhắn vừa đến, không bao giờ gửi nội dung bộ nhớ. Mọi lỗi, từ thiếu key tới quá thời hạn, đều chuyển sang bộ phân loại sinh văn bản kèm lý do được ghi lại. Nếu bộ phân loại đó cũng lỗi, tin nhắn được coi là `new_task` và xếp vào hàng đợi, không bao giờ bị bỏ. + +Mỗi quyết định trong lúc mode đang bật ghi một span `intent.decision`, cho biết bộ phân loại nào đã quyết định, độ tin cậy, lý do chuyển dự phòng nếu có và, ở mode shadow, Jev có đồng ý hay không. Nội dung tin nhắn không bao giờ được lưu. Đồng ý với bộ phân loại sinh văn bản không có nghĩa là chính xác, vì vậy hãy đánh giá `active` dựa trên một mẫu do người gắn nhãn. + +## Đánh giá ngữ nghĩa trace + +Đánh giá ngữ nghĩa đang ở giai đoạn beta và chỉ chạy khi `trace_semantic_enabled` được bật và đã có key. Jev đọc một bản tóm tắt có giới hạn, đã che thông tin nhạy cảm, của một trace đã xong rồi gắn nhãn: kết quả tác vụ, cách dùng tool, chất lượng truy xuất, hiệu quả, có cần người xem lại không và kiểu lỗi có khả năng xảy ra. Bạn có thể lấy mẫu trace, hoặc luôn đánh giá các trace bị lỗi, có giao việc, dùng nhiều tool hay có truy xuất. + +Các nhãn này **chỉ dùng để chẩn đoán**. Chúng thêm bộ lọc cho `dewee traces list`, chẳng hạn `--semantic-decision`, và không bao giờ thay đổi hành vi, prompt, tool hay trạng thái trace của agent. Khi quá thời hạn, lần đánh giá được ghi là thất bại và không bao giờ chặn agent. `dewee traces semantic config get` cho biết tính năng có đang bật hay không và vì sao. Xem [Tracing và quan sát hệ thống](/docs/concepts/tracing). + +## Giới hạn và an toàn + +Cả ba mục đích dùng chung một ngân sách yêu cầu và một circuit breaker trên mỗi tiến trình: + +- `reflex_budget_rpm` (mặc định 600) giới hạn số yêu cầu gửi đi mỗi phút, tính cả mỗi lần thử lại. Khi hết ngân sách, yêu cầu bị bỏ qua và dewee tiếp tục chạy mà không có Jev. +- Sau 5 lần lỗi liên tiếp, breaker mở trong 30 giây. Breaker mở chỉ có thể khiến dewee dễ dãi hơn: không có gì bị chặn và việc phân loại ý định chuyển sang bộ phân loại sinh văn bản. +- Lỗi `400`, `401` và `403` không làm breaker mở. Chúng cho thấy key hoặc bộ câu hỏi sai, và hiện trong `dewee reflex status` dưới dạng `misconfigured`. +- Ngân sách, breaker và bộ đếm tính theo từng tiến trình. Khi có nhiều replica gateway, mỗi replica có bộ riêng. + +Mọi đường xử lý đều fail open. Nếu TypeSafe chậm, ngừng hoạt động hay không kết nối được, dewee chạy như khi lớp quyết định đang tắt. + +## Lệnh + +| Lệnh | Dùng để | +|---|---| +| `dewee reflex status` | Xem key, phạm vi, mode và tỉ lệ lấy mẫu của từng seam, cấu hình phân loại ý định, breaker, ngân sách và bộ đếm. Thêm `--json` khi dùng trong script. | +| `dewee reflex config set` | Đổi mode, tỉ lệ lấy mẫu, ngưỡng và thời hạn; dùng `set-key` để lưu key | +| `dewee reflex test --set --state-file ` | Hỏi bộ câu hỏi của một seam với một mẫu và xem câu trả lời | +| `dewee reflex eval --labels [--sweep]` | Chấm điểm các ngưỡng trên một mẫu do người gắn nhãn | + +Các ngưỡng đi kèm là giá trị khởi đầu thận trọng, chưa được hiệu chỉnh. Hãy chạy `dewee reflex eval` với nhãn do người viết, không phải do model tạo ra, trước khi chuyển một seam từ `shadow` sang `gate`. + +## Liên quan + +- [Bộ nhớ và kho tri thức](/docs/concepts/memory-and-knowledge): các tác vụ bộ nhớ mà các seam kiểm duyệt đứng phía trước. +- [Tracing và quan sát hệ thống](/docs/concepts/tracing): span `reflex.decision`, `intent.decision` và bộ lọc đánh giá ngữ nghĩa. +- [Tham chiếu CLI](/docs/runtime/cli): toàn bộ lệnh `dewee reflex`. diff --git a/src/content/docs/vi/concepts/tracing.md b/src/content/docs/vi/concepts/tracing.md index 980f735..25b80f3 100644 --- a/src/content/docs/vi/concepts/tracing.md +++ b/src/content/docs/vi/concepts/tracing.md @@ -3,7 +3,7 @@ title: Tracing và quan sát hệ thống description: Những gì dewee ghi lại cho mỗi lượt chạy agent, trace giữ bao lâu, chi phí và mức sử dụng được tính ra sao, và cách đọc trace qua console, CLI, API hay OTel. section: concepts order: 10 -updated: 2026-09-25 +updated: 2026-10-10 --- Mỗi lượt chạy agent trong dewee đều để lại một trace: bản ghi về yêu cầu agent nhận được, các model và tool nó đã gọi, thời gian của từng bước, chi phí và kết quả cuối cùng. Trace là nơi đầu tiên cần xem khi một câu trả lời sai, chậm hoặc tốn kém. Trace được ghi ở chế độ nền, nên việc ghi lại không làm chậm lượt chạy. @@ -85,7 +85,7 @@ dewee traces timeline dewee --server https://dewee.example.com --token traces get -o json ``` -**Đánh giá ngữ nghĩa** đang ở giai đoạn beta và tắt mặc định. Khi người vận hành bật tính năng này và thêm API key của TypeSafe, các trace đã hoàn tất được gửi tới bộ phân loại bên ngoài đó, sau khi đã che thông tin xác thực và dữ liệu cá nhân, rồi được gắn các tín hiệu như tác vụ có thành công hay không. Các nhãn này trở thành bộ lọc bổ sung của `dewee traces list`, chẳng hạn `--semantic-decision`, và không bao giờ thay đổi cách agent chạy. `dewee traces semantic config get` cho biết tính năng có đang bật hay không và vì sao. +**Đánh giá ngữ nghĩa** đang ở giai đoạn beta và tắt mặc định. Khi người vận hành bật tính năng này và thêm API key của TypeSafe, các trace đã hoàn tất được gửi tới bộ phân loại bên ngoài đó, sau khi đã che thông tin xác thực và dữ liệu cá nhân, rồi được gắn các tín hiệu như tác vụ có thành công hay không. Các nhãn này trở thành bộ lọc bổ sung của `dewee traces list`, chẳng hạn `--semantic-decision`, và không bao giờ thay đổi cách agent chạy. `dewee traces semantic config get` cho biết tính năng có đang bật hay không và vì sao. Bộ phân loại này là Jev, cùng model mà [lớp quyết định](/docs/concepts/decision-layer) sử dụng. ## Xuất sang OpenTelemetry @@ -108,4 +108,5 @@ Span được xuất theo lô tối đa 100, mỗi 5 giây. Bộ xuất đã đ - [Vòng lặp agent](/docs/concepts/agent-loop): các bước mà mỗi span ghi lại. - [Nhóm agent và giao việc](/docs/concepts/agent-teams): theo dõi một yêu cầu qua nhiều agent. - [Workflow](/docs/concepts/workflows): lượt chạy workflow và span của các node. +- [Lớp quyết định](/docs/concepts/decision-layer): span `reflex.decision`, `intent.decision` và đánh giá ngữ nghĩa. - [Tham chiếu CLI](/docs/runtime/cli): toàn bộ lệnh `dewee traces` và `dewee usage`. diff --git a/src/content/docs/vi/runtime/cli.md b/src/content/docs/vi/runtime/cli.md index b458612..cb751fd 100644 --- a/src/content/docs/vi/runtime/cli.md +++ b/src/content/docs/vi/runtime/cli.md @@ -3,7 +3,7 @@ title: Tham chiếu CLI description: "Dòng lệnh dewee: global flag, cách CLI tìm gateway và key của bạn, định dạng đầu ra, và mọi nhóm lệnh cho agent, skill, workflow, bộ nhớ và quản trị." section: runtime order: 2 -updated: 2026-09-25 +updated: 2026-10-10 --- Chính binary `dewee` dùng để chạy gateway cũng là client dòng lệnh của nó. Phần lớn lệnh nói chuyện với một gateway đang chạy qua HTTP hoặc WebSocket, trên máy hay từ xa, nên người vận hành có thể viết script cho gần như mọi việc làm được trong console. Một vài lệnh bảo trì làm việc trực tiếp với cơ sở dữ liệu và chỉ dùng trên máy chủ. @@ -99,7 +99,7 @@ dewee agent chat --name support-bot --message "Summarise today's open tickets" | `dewee cron` | `list`, `get`, `create`, `update`, `toggle`, `run`, `runs`, `status`, `delete` | | `dewee workflows` | `list`, `show`, `create`, `validate`, `apply`, `export`, `publish`, `rollback`, `enable`, `disable`, `trigger`, `delete`, `node-types`; `runs` để liệt kê, xem, theo dõi, huỷ hoặc chạy lại | | `dewee heartbeat` | `get`, `set`, `toggle`, `test`, `logs`, `targets` | -| `dewee reflex` | `status`, `config`, `test`, `eval` | +| `dewee reflex` | `status`, `config`, `test`, `eval`; xem [Lớp quyết định](/docs/concepts/decision-layer) | Workflow có thể được giữ dưới dạng file và áp dụng từ CI: From 697dc7a6c0cce342925dd1f938b3c46977320a82 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 03:55:18 +0000 Subject: [PATCH 2/2] docs(decision-layer): legacy row cleanup and trace evaluation opt-out Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01CQ2pjZ3XkXuH6CF2epmD5i --- src/content/docs/en/concepts/decision-layer.md | 10 ++++++++-- src/content/docs/vi/concepts/decision-layer.md | 10 ++++++++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/concepts/decision-layer.md b/src/content/docs/en/concepts/decision-layer.md index c6e9899..b891eb6 100644 --- a/src/content/docs/en/concepts/decision-layer.md +++ b/src/content/docs/en/concepts/decision-layer.md @@ -148,12 +148,14 @@ A workspace admin can make the decision layer stricter for their own workspace, | Intent confidence floor | The higher of the two, so the workspace can only be stricter | | Intent time limit | The lower of the two | +Turning the decision layer off for a workspace also stops semantic trace evaluation for that workspace, so none of its content is sent to Jev. + Everything else, including the endpoint, model, provider, budget, key and retrieval settings, belongs to the instance and cannot be overridden. A value looser than the current instance value is rejected with a message that names the field. If the operator later tightens an instance value, the stricter instance value wins over an older override, and the console says so. ```bash dewee --tenant acme reflex settings # instance, override and effective values dewee --tenant acme reflex overrides set --mode shadow --seam-sampling kg_chunk=0.1 -dewee --tenant acme reflex overrides set --enabled=false # this workspace never calls Jev for memory admission or intent +dewee --tenant acme reflex overrides set --enabled=false # this workspace never calls Jev dewee --tenant acme reflex overrides reset mode seam_sampling.kg_chunk dewee --tenant acme reflex decisions --limit 25 # recent decisions, newest first ``` @@ -166,7 +168,11 @@ The same three endpoints are available to a customer API key with the `integrati ### Upgrading -Earlier versions stored decision layer settings for whichever workspace the operator was signed in to. dewee now reads instance values from master scope only. If a workspace still holds older rows, the gateway logs a warning at startup naming the workspace and the keys. Re-apply those values at master scope with `dewee reflex config set` and `set-key`. +Earlier versions stored decision layer settings for whichever workspace the operator was signed in to. dewee now reads instance values from master scope only. If a workspace still holds older rows, the gateway logs a warning at startup naming the workspace and the keys. Re-apply those values at master scope with `dewee reflex config set` and `set-key`, then remove the old rows from the workspace: + +```bash +dewee --tenant acme reflex overrides reset legacy_instance_rows +``` ## Limits and safety diff --git a/src/content/docs/vi/concepts/decision-layer.md b/src/content/docs/vi/concepts/decision-layer.md index 860c8e1..22ed35f 100644 --- a/src/content/docs/vi/concepts/decision-layer.md +++ b/src/content/docs/vi/concepts/decision-layer.md @@ -148,12 +148,14 @@ Admin của một workspace có thể đặt lớp quyết định chặt hơn c | Độ tin cậy tối thiểu cho ý định | Giá trị cao hơn trong hai, nên workspace chỉ có thể chặt hơn | | Giới hạn thời gian cho ý định | Giá trị thấp hơn trong hai | +Khi tắt lớp quyết định cho một workspace, đánh giá ngữ nghĩa trace của workspace đó cũng dừng, nên không có nội dung nào của workspace được gửi tới Jev. + Mọi thứ khác, gồm endpoint, model, nhà cung cấp, ngân sách, key và cài đặt truy xuất, thuộc về hệ thống và không ghi đè được. Một giá trị lỏng hơn giá trị hiện tại của hệ thống sẽ bị từ chối, kèm thông báo nêu rõ trường đó. Nếu sau này người vận hành siết chặt một giá trị của hệ thống, giá trị chặt hơn đó thắng giá trị ghi đè cũ, và console sẽ báo điều này. ```bash dewee --tenant acme reflex settings # giá trị của hệ thống, ghi đè và có hiệu lực dewee --tenant acme reflex overrides set --mode shadow --seam-sampling kg_chunk=0.1 -dewee --tenant acme reflex overrides set --enabled=false # workspace này không gọi Jev cho kiểm duyệt bộ nhớ hay phân loại ý định +dewee --tenant acme reflex overrides set --enabled=false # workspace này không gọi Jev dewee --tenant acme reflex overrides reset mode seam_sampling.kg_chunk dewee --tenant acme reflex decisions --limit 25 # các quyết định gần đây, mới nhất trước ``` @@ -166,7 +168,11 @@ API key của khách hàng có scope `integrations.manage` cũng dùng được ### Nâng cấp -Các phiên bản trước lưu cài đặt lớp quyết định vào workspace mà người vận hành đang đăng nhập. Giờ dewee chỉ đọc giá trị của hệ thống từ phạm vi master. Nếu một workspace vẫn còn các dòng cũ, gateway ghi cảnh báo lúc khởi động, nêu tên workspace và các khoá. Hãy đặt lại các giá trị đó ở phạm vi master bằng `dewee reflex config set` và `set-key`. +Các phiên bản trước lưu cài đặt lớp quyết định vào workspace mà người vận hành đang đăng nhập. Giờ dewee chỉ đọc giá trị của hệ thống từ phạm vi master. Nếu một workspace vẫn còn các dòng cũ, gateway ghi cảnh báo lúc khởi động, nêu tên workspace và các khoá. Hãy đặt lại các giá trị đó ở phạm vi master bằng `dewee reflex config set` và `set-key`, rồi xoá các dòng cũ khỏi workspace: + +```bash +dewee --tenant acme reflex overrides reset legacy_instance_rows +``` ## Giới hạn và an toàn