docs: align Ollama tool-calling guidance - #9
Draft
mzkarami wants to merge 7 commits into
Draft
Conversation
The `clarify` tool's multiple-choice prompts flattened to a numbered text
list on Photon/iMessage, even though iMessage has a native poll bubble and
spectrum-ts already exposes it via the `poll()` content builder. Two gaps
caused the flattening:
* Outbound: the sidecar only had `/send` (text); there was no way to send
a poll, so the base adapter's numbered-text fallback was used.
* Inbound: `normalizeContent()` handled only text/attachment/voice, so a
poll vote (`poll_option`) was dropped on the floor ("[Photon content
type not handled: poll_option]") and never resolved the clarify.
Fix, end to end:
* Sidecar: import `poll` from spectrum-ts; add a `/send-poll` route
(`space.send(poll(title, ...options))`); serialize inbound `poll_option`
(the vote: chosen title + selected bool) and `poll` content in
`normalizeContent()`.
* Adapter: override `send_clarify` — for choices, send a native poll via
`_sidecar_send_poll` and call `mark_awaiting_text` so the gateway's
existing pending-clarify text-intercept resolves the answer; open-ended
clarifies keep the plain-text path. Inbound `poll_option` selections are
dispatched as a plain-text MessageEvent carrying the chosen option
(deselections / empty votes are dropped). If the poll send fails (an
older sidecar without `/send-poll`, or a send error) it falls back to the
numbered-text clarify, so nothing regresses on a half-upgraded restart.
No new model tool, no new env var, no core change — the capability lives at
the platform edge. The poll vote reuses the existing clarify text-intercept
resolution path, so no new gateway resolution mechanism is introduced.
Tests: tests/plugins/platforms/photon/test_poll_clarify.py — inbound vote ->
choice text, deselection/empty-vote dropped, send_clarify sends a poll +
enables text-capture, open-ended stays text, and poll-failure falls back to
the text list. Full photon suite green.
Contributed by Vaibhav Sharma (X: @vabbyshabby).
for poll clarify Follow-up to the NousResearch#48194 pick: it was written before NousResearch#43665 landed and re-added its own /send-poll sidecar route and poll import. Collapse the duplicates: - keep NousResearch#43665's /send-poll route (>=2 trimmed string options) as the single sidecar implementation; drop NousResearch#48194's variant - drop the duplicated poll import in the sidecar destructure - make adapter.send_poll() a thin wrapper over _sidecar_send_poll(), the one /send-poll client (shared with the poll-backed clarify path), and align its validation to the sidecar's >=2-options contract
imessage.effect.message crashed the sidecar at import against SDK stubs/
builds lacking the effect surface (caught by the patch-failure health test).
Optional-chain with {} fallback; /send-effect rejects cleanly instead.
mzkarami
force-pushed
the
auto/nightly-ollama-tool-docs-20260729
branch
from
July 29, 2026 05:13
49337bf to
5ec47f8
Compare
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
4 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.
What does this PR do?
Aligns the Ollama troubleshooting guidance with the model table:
gemma2:27bis documented as chat-only, so the troubleshooting section no longer recommends it for tool calling. The same correction is applied to the Simplified Chinese translation.Public discovery signal: NousResearch#73735. The original public guide PR, NousResearch#5842, records that
gemma2:9b/27bwere tested without Ollama tool-call support.Duplicate checks searched open and recently closed/merged upstream PRs and issues for
gemma2,tool calling,Ollama, anddocs. No open PR addresses this contradiction; NousResearch#5842 is the original closed guide contribution rather than a competing fix.Related Issue
Refs NousResearch#73735
Type of Change
Changes Made
website/docs/guides/local-ollama-setup.md.website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/local-ollama-setup.md.How to Test
git diff --check.website/, runnpm run lint:diagramswith CI'sascii-guard==2.3.0andpyyaml==6.0.3installed.website/, runnpm run buildand confirm both English and Simplified Chinese sites build successfully.Checklist
Code
fix(scope):,feat(scope):, etc.)pytest tests/ -qand all tests pass — N/A: documentation-only change; the docs checks below passedDocumentation & Housekeeping
docs/, docstrings) — or N/Acli-config.yaml.exampleif I added/changed config keys — N/ACONTRIBUTING.mdorAGENTS.mdif I changed architecture or workflows — N/AScreenshots / Logs
git diff --checkpassed.npm run lint:diagramspassed.npm run buildpassed for the English and Simplified Chinese documentation sites (with existing broken-link warnings).Risk
Low. This changes four documentation lines and no runtime behavior.
Human gate
This is a fork draft prepared for human review. Submission to the upstream repository requires explicit human approval in a separate interactive session.