All changes in feature/doc_improvements branch - #555
Draft
atp-epam wants to merge 103 commits into
Draft
Conversation
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <copilot@github.com>
There was a problem hiding this comment.
Overall impression about this article (in comparison with the original version) is mixed:
- great work on simplification, it's easier to read, looks lighter, "reference" is taken out to the separate article (maybe a good move actually, though inline pseudo-code entries were demonstrating the concepts)
- at the same time, it feels less structured, lacks "technical touch" and "strictness"; it can be a downside for the "expert" readers. A level of details is lower, some inline links to other sections are missing (publication, PRK, sharing, configuration) - they can be found at the bottom, but again, it requires extra moves from the reader.
I cannot say I found any literally "errors" - no, everything is pretty accurate. But I have doubts in how a first-time reader without any DIAL background would be able to understand it. Authorization is pretty sensitive topic and deserves details.
But this is subjective, I won't argue if this format is adopted.
Also a couple of smaller notes are inline.
- mcp-server-integration: MCP OAuth config key 'audience' -> 'aud' - deployments/images: dialog title 'Save new version' -> 'Save as new version' - chat-user-guide/files: 'My files' -> 'My Files' - chat-user-guide/marketplace-and-apps: filter label 'Source' -> 'Sources' - understand-dial/dial-evolution: link the public roadmap (dialx.ai/roadmap) - sdk-reference/dial-app: heartbeat applies to SSE streaming responses only Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per PR #555 review (andrii-novikov: 'propose to remove QuickApps 1.0'; they are no longer fully supported) and the team decision to make the section Quick App 2.0-only: - Delete the 2.quick-app-original/ subtree (create-and-configure, reference, migrate-to-2). - Remove the 'Quick App (original)' category from sidebars-v2.js. - Rewrite 0.index.md as Quick App 2.0-only: drop the two-type tip, the 2.0-vs-original comparison, the legacy properties section, and the original next-steps block; correct the tools/properties tables and the minimal config (deployment_id, conversation_starters, RAG-as-tool). - coverage-status.md: drop the Quick App (original) section; refresh RAG/conversation_mode wording. - Repoint inbound links in operating-dial/troubleshooting.md and cloud-deployment/7.quick-apps-installation.md to the 2.0 docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…[PR #555] Fixes factual errors flagged by andrii-novikov in PR #555, verified against epam/ai-dial-quickapps-backend@development (generated-app-schema.json, application-schema.md, docker_compose_files/.../applications.json) and epam/ai-dial-core@development (docs/open_api_core.yaml). Schema/field corrections across create-via-*, tutorials, examples, and the tool-sets reference: - orchestrator deployment: 'name' -> 'deployment_id' ('name' is a deprecated legacy alias in the schema). - top-level 'starters' string array -> structured 'conversation_starters' ({intro_text?, starters:[{title,text}]}); plain 'starters' is deprecated. - config.json envelope: 'applicationTypeSchemaId' moved to top level (was wrongly nested under 'reference'). - registration blocks: add 'dial:applicationTypeSchemaEndpoint' (/v1/configuration-support/application-schema) + the assistant-attachments flag; note the schema-endpoint approach is recommended (Core >= 0.41.0). - tool input parameter 'text' -> 'query' (matches the dial_rag tool convention). - max_iterations: documented default is 15; moved out of deployment.parameters where misplaced; fixed 'N iterations = N tool calls' wording (one orchestrator operation may issue several tool calls). - content_propagation.propagate_history -> conversation_mode.resumable (propagate_history is deprecated). - RAG reframed as the predefined 'dial_rag' tool (params query + attachment_urls), not a built-in feature; 'contexts' documented as separate document grounding. - dial-deployment-simple no longer described as passing full conversation context by default. Reviewer-requested open items (applied as requested; flagged here): - create-via-api.md: replaced the incorrect 'POST /v1/applications/{appId}' with the real API from ai-dial-core OpenAPI: get bucket via GET /v1/bucket, then PUT/GET/DELETE /v1/applications/{bucket}/{application_path} (saveCustomApplication/getCustomApplication/deleteCustomApplication), list via GET /openai/applications. Requested by andrii-novikov ('could not find the endpoint; others outdated too'). - Removed '{{variable}}' system-prompt substitution CLAIMS from 1.create-via-ui.md and 9.tool-sets/4.reference.md at andrii-novikov's request. NB: the shipped QuickApps schema still exposes a 'system_prompt.variables' field, so this claim removal deviates from the source schema and should be re-confirmed with the QuickApps team. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
] Follow-up to the QA 2.0 correctness pass, addressing two remaining andrii-novikov comments verified against ai-dial-core@development OpenAPI and the quickapps schema: - 6.tutorial-agent-loop-api.md ('core routes are incorrect'): add the GET /v1/bucket lookup and switch create/retrieve/update to the real bucket-scoped routes (PUT/GET /v1/applications/{bucket}/{application_path}), replacing the invalid POST /v1/applications/{appId}. - 4.working-with-tools-and-agents.md ('there is no default value'): drop the 'Default.' label from the streamable_http MCP protocol row (the schema defines no default protocol). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
] Part of standardizing 'Tool Set' -> 'Toolset/Toolsets' (VolhaBazhkova, PR #555). Renamed the NEW-instance routes and wired redirects: - git mv 6.chat-user-guide/4.tool-sets.md -> 4.toolsets.md - git mv .../quick-app-2/9.tool-sets/ -> 9.toolsets/ (6 pages) - sidebars-v2.js: updated the 7 tool-sets route ids + the Toolset labels - docusaurus.config.js: add @docusaurus/plugin-client-redirects mapping the old /.../tool-sets URLs to the new /.../toolsets URLs (NEW instance) - package.json/lock: add @docusaurus/plugin-client-redirects (^3.x) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…outes/redirects [PR #555] Canonical term (user decision per VolhaBazhkova, PR #555): one word Toolset/Toolsets, matching DIAL Chat and DIAL Admin. (Route files were renamed in the previous commit db36dec.) - Case-mapped prose/heading/label sweep across all docs_v2 + docs-planning/glossary.md: 'Tool Set(s)'/'Tool set' -> Toolset(s); 'tool set(s)' -> toolset(s); hyphen slugs/anchors tool-set(s) -> toolset(s) (headings + inbound #anchors). Glossary '### Tool Set' -> '### Toolset' (+ cross-references). - sidebars-v2.js: 7 'tool-sets' route ids -> 'toolsets'; Toolset labels. - docusaurus.config.js + package.json/lock: @docusaurus/plugin-client-redirects mapping old /.../tool-sets URLs to /.../toolsets (NEW instance). - CLAUDE.md: prose updated + new Key-conventions bullet making Toolset/Toolsets the canonical term. - Untouched: code identifiers (tool_sets, client_toolset, web_api_toolset, mcp_toolset, config keys) and the verbatim upstream schema snapshot 7.reference/changelog/quickapp2-schema.json. Build green (onBrokenLinks/onBrokenAnchors both throw). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…[PR #555] DIAL's Helm charts replaced the bundled Bitnami Redis subchart with Valkey (verified: epam/ai-dial-helm@main, dial-core 6.0.0 depends on the valkey subchart; values key redis: -> valkey:). Addresses kamiakou-epam's ~20 'to be reviewed re Redis->Valkey' comments and alexey-ban's 'no longer Bitnami Redis' (PR #555). - cloud-deployment 0.index/1-4: in-cluster bundled store 'Redis' -> Valkey (stack lists, diagrams, narrative); managed-cache examples note a Redis-compatible service. - production-readiness/1.high-availability: 'Bitnami redis-cluster subchart' -> Valkey subchart; chart value core.redis.enabled -> core.valkey.enabled; Step 4 heading generalized. - production-readiness 0.index/3/4/5: cache component -> Valkey. Kept unchanged (Valkey is Redis-protocol-compatible): DIAL Core connection config aidial.redis.* and redis:// URIs, managed-service names (ElastiCache, Azure Cache for Redis, Memorystore), and the local docker-compose Redis image. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… [PR #555] Conceptual/architecture pages now name the bundled in-memory store Valkey (Redis-compatible), per the Helm chart change (dial-core 6.0.0 valkey subchart). - dial-stack: component row -> 'Valkey (Redis-compatible)' + note that any Redis-compatible managed service can be used instead (YuriyIvon, dial-stack:33). - architecture-highlights, glossary, what-is-dial: 'Redis' cache -> Valkey. Left as-is: developer-quick-start (describes the local docker-compose stack, which still ships the Redis image) and settings.json/3.redis.md (Core's Redis-protocol connection config). NB: the persistant-layer.svg diagram still labels the cache 'Redis' and should be regenerated separately. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
] Strike through A1 (+ B2.5, and the Valkey clauses of B8.2/B8.5) with a done banner and commits da868bc / 931a26c; note kept protocol/local/managed refs, the deferred persistant-layer.svg diagram, and the still-open non-Valkey B8 items. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
17 participants
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.
this is for @YuriyIvon
check BRANCH_GUIDE.md first!