docs: README sequence diagram + chatbot learns the architecture#32
Merged
Conversation
…architecture - README: add a step-by-step proxy-request sequence diagram (collapsible) in 'How Blindfold fixes it', linking to system_design.md's full diagram set. - Chatbot: add curated KB entries system_architecture + three_secret_paths (pointing to system_design.md) with classifier patterns + Intent types. Verified routing at conf 1.00. (The extract run merged system_design.md to 0 new entries — its content mapped onto existing intents — so these are curated.) Co-authored-by: algsoch <algsoch@gmail.com>
PR Summary by QodoDocs: add proxy sequence diagram + teach chatbot architecture intents
AI Description
Diagram
High-Level Assessment
Files changed (4)
|
Code Review by Qodo
1. Overconfident generic intents
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+714
to
+739
| { | ||
| intent: "system_architecture", | ||
| patterns: [ | ||
| { type: "phrase", value: "system design", weight: 6 }, | ||
| { type: "phrase", value: "architect", weight: 5 }, | ||
| { type: "phrase", value: "design of", weight: 3 }, | ||
| { type: "phrase", value: "how is it built", weight: 4 }, | ||
| { type: "phrase", value: "how is blindfold built", weight: 5 }, | ||
| { type: "phrase", value: "how does the whole system", weight: 5 }, | ||
| { type: "phrase", value: "components", weight: 2 }, | ||
| { type: "phrase", value: "how it works end to end", weight: 4 }, | ||
| ], | ||
| examples: ["how is Blindfold architected?", "explain the system design", "what are the components?"], | ||
| }, | ||
| { | ||
| intent: "three_secret_paths", | ||
| patterns: [ | ||
| { type: "phrase", value: "three ways", weight: 6 }, | ||
| { type: "phrase", value: "three paths", weight: 6 }, | ||
| { type: "phrase", value: "proxy vs release", weight: 7 }, | ||
| { type: "phrase", value: "release vs proxy", weight: 7 }, | ||
| { type: "phrase", value: "secret paths", weight: 6 }, | ||
| { type: "phrase", value: "release broker", weight: 4 }, | ||
| ], | ||
| examples: ["what are the three secret paths?", "proxy vs release?"], | ||
| }, |
There was a problem hiding this comment.
1. Overconfident generic intents 🐞 Bug ≡ Correctness
The new intent patterns include very generic phrases (e.g., "components", "three ways") that are matched via substring and can yield confidence=1.0 with only a single hit, causing incorrect intent routing and overly confident answers for minimally-related queries.
Agent Prompt
### Issue description
New intent patterns for `system_architecture` and `three_secret_paths` include extremely generic phrases (e.g., `components`, `three ways`). Because phrase matching is substring-based and the engine’s confidence formula scales directly with raw pattern weight, these generic matches can produce **confidence=1.0** and route to the wrong intent.
### Issue Context
- `phrase` patterns match via `text.includes(...)`.
- Classification `score` is the sum of matched pattern weights.
- Engine confidence is `min(1, patternScore*0.5 + kbConfidence*0.4 + audienceBonus)`; with KB confidence ~0.96–0.97, even a single low-signal match can clamp to 1.
### Fix Focus Areas
- packages/chatbot/src/intents.ts[714-739]
### Suggested fix
- Remove or replace overly generic patterns:
- Drop `{ type: "phrase", value: "components", ... }`.
- Drop `{ type: "phrase", value: "three ways", ... }`.
- Prefer more specific phrases/regex that encode Blindfold context, e.g.:
- `regex: "\\b(blindfold|tdx|enclave)\\b.*\\b(architecture|system design|components)\\b"`
- `regex: "\\bthree\\b.*\\b(secret paths|sealed secret|proxy vs release|forward vs release)\\b"`
- If you want to keep a “components” trigger, make it contextual (e.g., `"blindfold components"`) and/or reduce weight so it can’t overwhelm unrelated intents.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+20176
to
+20181
| "links": [ | ||
| { | ||
| "label": "system_design.md#4--the-three-secret-paths", | ||
| "url": "system_design.md", | ||
| "type": "code" | ||
| } |
There was a problem hiding this comment.
2. Kb deep-link url mismatch 🐞 Bug ≡ Correctness
The new kb-three-secret-paths entry’s link label includes the #4--the-three-secret-paths fragment, but the URL omits it, so the rendered Sources link won’t navigate to the intended section.
Agent Prompt
### Issue description
A KB entry link label suggests a deep link (includes a `#...` fragment) but the actual `url` target is missing that fragment. The responder renders links using `link.url`, so users will not land on the intended section.
### Issue Context
In `kb-three-secret-paths`, the link object is:
- label: `system_design.md#4--the-three-secret-paths`
- url: `system_design.md`
### Fix Focus Areas
- packages/chatbot/data/knowledge.json[20176-20181]
### Suggested fix
Update the URL to include the anchor:
- `"url": "system_design.md#4--the-three-secret-paths"`
(Confirm the exact heading slug in `system_design.md` if GitHub’s generated anchor differs.)
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to system_design.md:
system_architecture+three_secret_paths(linking to system_design.md) with classifier patterns +Intenttypes. Questions like 'how is Blindfold architected', 'system design', 'three secret paths', 'proxy vs release' now route at conf 1.00.Co-authored-by: algsoch algsoch@gmail.com
Summary by cubic
Added a step‑by‑step proxy request sequence diagram to the README and taught the chatbot the system architecture so it can answer “how is Blindfold built” and “three secret paths” with accurate routing. This clarifies how the proxy works and improves answers to architecture questions.
system_design.md.system_architecture,three_secret_paths), added intents and patterns inpackages/chatbot/src/intents.tsand types insrc/types.ts; questions like “system design” and “proxy vs release” now route at confidence 1.00.Written for commit aadde39. Summary will update on new commits.