@widgex/wgx 0.0.0-stage → 0.4.1

package/python/xactor/man/ask_model.md

@@ -0,0 +1,110 @@
+# api.ask_model(model, prompt, system=None, temperature=None, max_tokens=None, stop=None, timeout_seconds=None) -> str
+
+<!-- group: Sessions -->
+<!-- also: complete, completion, generate, llm, sample, smiles, local-model -->
+
+Ask one model one question. No tools, no subagent, no session. Never asks.
+
+`api.agent` hands *work* over — the thing on the other end gets your shell, reads
+files, runs code, and decides for itself when it is done. This hands over
+nothing. It sends a prompt to a model and gives you back what it said, as a
+string.
+
+## When you need it
+
+Some models cannot call tools. Not "would rather not" — were never trained to,
+and will never emit a tool call however you prompt them. A chemical language
+model that answers in SMILES strings, a classifier, a fine-tune that returns one
+line: these cannot participate in an agent loop, because an agent loop is made of
+tool calls.
+
+`api.agent` refuses them by name, and so does the session picker and the harness
+config. This is the way in.
+
+    smiles = await api.ask_model(
+        'ollama/smiley:latest',
+        'Generate a drug-like molecule with logP below 5 containing a '
+        'piperazine ring. Reply with the SMILES string only.',
+    )
+
+You can ask any model this way, not only the tool-less ones — it is simply a
+cheaper shape when all you want is an answer. But for a tool-less model it is the
+only shape available.
+
+## What comes back is data, not work done
+
+The string has been checked by nothing. The model that wrote it had no files, no
+shell, and no way to verify its own answer — and it will answer confidently
+whatever you ask it, including about things it has never seen. It does not refuse
+out-of-scope questions; it makes something up.
+
+So: parse it, validate it, run it past a real tool, throw away what does not hold
+up. Do not hand one of these a coding task, a file path, or a question about this
+repository.
+
+## Several answers at once
+
+There is deliberately no `n`. The OpenAI parameter of that name is not
+implemented by the local runtimes this call exists for, so passing it would
+quietly return one sample while looking like it returned eight.
+
+Ask several times instead. Every api call on this shell is a coroutine, and the
+bridge multiplexes them, so this really is concurrent:
+
+    import asyncio
+
+    brief = 'Generate a drug-like molecule with a piperazine ring. SMILES only.'
+    candidates = await asyncio.gather(*[
+        api.ask_model('ollama/smiley:latest', brief, temperature=1.0)
+        for _ in range(8)
+    ])
+
+Raise `temperature` when you do this. At the model's default you may get the same
+answer eight times, which is not a bug and is not useful either.
+
+## Arguments
+
+| | |
+|---|---|
+| `model` | `'provider/model'`, or a bare id when only one provider offers it. Unknown ids are refused with the list of what is available. |
+| `prompt` | The whole question. It sees nothing of this conversation. |
+| `system` | A system prompt, if the model expects one. Omitted sends **none at all**, not an empty one — for a fine-tune trained on one exact prompt shape those are different prompts. |
+| `temperature` | 0 to 2. Omit for the model's own default. |
+| `max_tokens` | Cap on the answer. See below. |
+| `stop` | Up to four stop sequences. A bare string is fine. |
+| `timeout_seconds` | Default 300. |
+
+## Hitting `max_tokens` raises
+
+A completion that hit its cap does not come back as a short answer — it raises.
+
+This is deliberate and it is about the models this call serves. A SMILES string
+truncated mid-token still parses and still looks like a molecule. Returning it
+would let you file something chemically meaningless as a result, and nothing
+downstream would catch it. If you get `AskModelTruncated`, raise `max_tokens` and
+ask again.
+
+## The first call is slow
+
+A local model that is not already resident spends thirty seconds or more loading
+before it says its first word. That is why the default timeout is 300 seconds and
+not 30. Subsequent calls are fast until the server unloads it again.
+
+`AskModelTimeout` says this in its message, so you can tell it apart from a model
+that is genuinely stuck.
+
+## What it refuses
+
+- **A model served by a CLI that runs its own agent loop** — Claude Code, Gemini,
+  Antigravity. They expose no completion endpoint. Refused by name rather than
+  quietly answered by a different model, because a fabricated answer attributed
+  to a model that never saw the prompt is worse than an error.
+- **An unknown or disabled model** — with the list of what is available, and the
+  user's own notes on what each is for.
+
+## Related
+
+- [[agent]] — hand over work, to a model that can act
+- [[children]] — what you have already started
+
+Never gated. It starts nothing, outlives nothing, and touches no file.

package/python/xactor/man/ask_reference.md

@@ -0,0 +1,56 @@
+# api.ask_reference(ref, question, timeout=300) -> dict
+<!-- group: Sessions -->
+
+Ask an earlier conversation that the person attached to this chat.
+
+A `<reference>` block at the top of a prompt is a summary and a changelog of
+work done somewhere else. When that is not enough — you need to know why
+something was decided, what was tried and dropped, or what a file looked like
+at the time — ask it.
+
+```python
+r = await api.ask_reference(
+    "Widgex/Widgex/Browser-Blocked",
+    "Did the fix change input coordinates, or only the screencast metadata?",
+)
+print(r["answer"])
+```
+
+## What happens
+
+The first question starts a **fork** of that conversation: a new agent, filed
+under your task, that begins with the summary and changelog and reads the old
+transcript as it needs to. Every later question for the same reference goes to
+that same fork, so it remembers what you already asked. The person can open it
+and read the exchange.
+
+## Options
+
+- **`ref`** — the `id` of the reference block. Only a reference attached to
+  this conversation can be asked; anything else is refused, and the error lists
+  what is attached.
+- **`question`** — one question, specific. The fork quotes the passage an
+  answer rests on when you would need to check it; ask for that when it matters.
+- **`timeout`** — seconds to wait. Raise the exec's own `timeout_seconds` past
+  it.
+
+## Returns
+
+`{answer, session, node, status, error?}`
+
+- `status: 'done'` — `answer` is the reply.
+- `status: 'timeout'` — no reply yet, `answer` is empty, and the fork is still
+  working. It was not stopped: call again to wait for it.
+- `status: 'error'` — the fork's turn failed; `error` says how.
+
+Raises when the reference is not attached here, or when the conversation it
+points at is no longer in the store.
+
+## Do not
+
+- **Do not ask what the block already says.** A fork is a real agent and costs
+  like one; the summary and changelog are free.
+- **Do not treat an answer as a fact about this working copy.** It describes
+  another one. Check any file, function or commit it names before acting on it.
+- **Do not ask it to make changes.** It is told not to, and it is standing in
+  your working copy.

package/python/xactor/man/ask_user.md

@@ -0,0 +1,103 @@
+# api.ask_user(question, options, header=None, multi_select=False) -> str
+<!-- group: Talking to the user -->
+
+Ask a multiple-choice question and block for the answer. Not gated.
+
+**The answer is arbitrary text.** The card always lets the user type something
+of their own instead of picking, so an option label is a suggestion, not a
+constraint on what comes back.
+
+## Options
+
+- **`question`** — the question, as a full sentence. This string is also the
+  key the answer is looked up under, so it must be non-empty.
+- **`options`** — 2 to 4 choices. Either plain strings, or dicts of
+  `{"label": str, "description": str}` where the description explains the
+  trade-off. **Put your recommendation first**, and say so in its label.
+- **`header`** — a short category chip on the card, ~12 characters:
+  `"Auth method"`, `"Library"`. Defaults to `"Question"`.
+- **`multi_select`** — allow more than one choice. The answer then comes back
+  as the chosen labels joined by `", "`.
+
+At least two options are required; a one-option question is rejected with a
+`ValueError` before anything reaches the user.
+
+## Returns
+
+A `str`: the label the user chose, the labels they chose joined by `", "`, or
+whatever they typed instead.
+
+Raises `RuntimeError` if they dismissed the card without answering. That aborts
+the exec, so do not put irreplaceable work after the call in the same block.
+
+## Examples
+
+```python
+answer = await api.ask_user(
+    "Which database should the new service use?",
+    [
+        {"label": "Postgres (Recommended)",
+         "description": "Already used by the billing service; migrations exist."},
+        {"label": "SQLite",
+         "description": "No server to run, but no concurrent writers."},
+    ],
+    header="Database",
+)
+return answer
+```
+
+Handling the answer as text, which is what it is:
+
+```python
+answer = await api.ask_user("Ship it now, or wait for review?",
+                            ["Ship now", "Wait for review"])
+if "ship" in answer.lower():
+    ...
+else:
+    # covers "Wait for review" *and* "wait until Thursday please"
+    ...
+return answer
+```
+
+Multi-select:
+
+```python
+picks = await api.ask_user(
+    "Which checks should run in CI?",
+    ["Unit tests", "Type check", "Lint", "Bundle size"],
+    header="CI checks", multi_select=True,
+)
+return [p.strip() for p in picks.split(",")]
+```
+
+## Getting it wrong
+
+**Comparing against your own labels with `==`.**
+
+```python
+# Wrong — silently takes the else branch when the user typed anything.
+if answer == "Postgres (Recommended)":
+    ...
+
+# Right — the answer may be free text, so read it rather than match it.
+if "postgres" in answer.lower():
+    ...
+```
+
+**Asking for approval of a plan you are about to execute.** Permission prompts
+already cover the gated calls. Use `ask_user` for a decision that changes
+*what* you build, not to seek reassurance.
+
+**Asking what you could find out.** If the answer is in the repo, read the
+repo. A question the user has to answer costs them attention you can only spend
+once.
+
+**Options that are not mutually exclusive, without `multi_select=True`.** The
+user then has to type, and you lose the structure you asked for.
+
+**Losing work to a dismissal.** The `RuntimeError` kills the whole exec. Ask
+first, act after — ideally in the next exec.
+
+## See also
+
+`request_user_action`, `todo_write`, `permissions`