26 KiB
markup, title, description, import
| markup | title | description | import | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| occlusion | ext/ai/llm | Marqdo LLM intelligence primitive — ask / stream / collect / named handles. OpenAI-compatible and Ollama HTTP stay behind the semantic surface. |
|
Choose the public model resource here for ask, stream and collected response behavior. The AI entry provides an offline event workflow; the adapter entry owns provider configuration and transport shapes. Agents and workbook orchestration belong in agent.mq.md. A created handle is configuration, not proof that authentication or a model request succeeded. Keep transport errors, semantic events and usage counters visible when extending this file.
load_env
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load .env from cwd (optional path=). Does not override existing variables. |
Use path=None as the inputs for this operation.
Load .env from cwd (optional path=). Does not override existing variables.
Return Load dotenv.
collect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Collapse a stream event list to final answer text. Accepts semantic events (delta / text / done.result / error.message) and native-plugin raw SSE frames (type=data with OpenAI chunk JSON in data). Alias: stream_result. |
Use events as the inputs for this operation.
Collapse a stream event list to final answer text.
Accepts semantic events (delta / text / done.result / error.message) and
native-plugin raw SSE frames (type=data with OpenAI chunk JSON in data).
Alias: stream_result.
We retain answer = "".
- [ev](遍历 events 为 ev)
We retain
t= [Read the type field](json.get(value=ev, key="type")).t== "done" We retaindone_r= [Read the result field](json.get(value=ev, key="result")).done_rWe retain answer =done_r.-
**_ = 1**t== "error" We retainem= [Read the message field](json.get(value=ev, key="message")).emWe retain answer =em.-
**_ = 1**t== "delta"t== "text" We retainchunk= [Read the text field](json.get(value=ev, key="text")).chunkWe retain answer = answer + chunk.-
**_ = 1**t== "data" We retainraw= [Read the data field](json.get(value=ev, key="data")).raw1.raw== "[DONE]" _ = 1 2. * We retainparsed= Parse the JSON transport text.parsedWe retainchoices= [Read the choices field](json.get(value=parsed, key="choices")).choicesWe retainc0= Read 1 field). We retaindelta= [Read the delta field](json.get(value=c0, key="delta")). 1.deltaWe retainpiece= [Read the content field](json.get(value=delta, key="content")).pieceWe retain answer = answer + piece.-
msg= [Read the message field](json.get(value=c0, key="message")).msgWe retainpiece= [Read the content field](json.get(value=msg, key="content")).pieceWe retain answer = answer + piece.-
**_ = 1**-
**_ = 1**-
**_ = 1**
- not
answerWe retain answer = "". Return answer.
collect_usage
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Best-effort total_tokens from stream frames (requires stream_options.include_usage). |
Use events as the inputs for this operation.
Best-effort total_tokens from stream frames (requires stream_options.include_usage).
We retain tokens = None.
events
- [ev](遍历 events 为 ev)
We retain
t= [Read the type field](json.get(value=ev, key="type")). We retain raw = None.t== "data" We retainraw= [Read the data field](json.get(value=ev, key="data")).-
u0= [Read the usage field](json.get(value=ev, key="usage")).u0We retaintt0= [Read the total_tokens field](json.get(value=u0, key="total_tokens")). 1.tt0!= None We retain tokens =tt0.raw- not
raw== "[DONE]" We retainparsed= Parse the JSON transport text. 1.parsedWe retainu= [Read the usage field](json.get(value=parsed, key="usage")).uWe retaintt= [Read the total_tokens field](json.get(value=u, key="total_tokens")).tt!= None We retain tokens =tt. Return tokens.
stream_result
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Compatibility alias for collect. |
Use events as the inputs for this operation.
Compatibility alias for collect.
Return Collect.
usage_from
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| data | any | required | Structured input supplied to this adapter or resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Extract {prompt_tokens,completion_tokens,total_tokens} from an OpenAI-shaped response map (or empty zeros). |
Use data as the inputs for this operation.
Extract {prompt_tokens,completion_tokens,total_tokens} from an OpenAI-shaped response map (or empty zeros).
Return Usage from.
create
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| backend | any | "openai-compatible" | Configured execution or provider backend |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Factory for an LLM handle (same as constructing # llm). Env fallbacks apply inside the constructor. Optional name= tags the handle (fast / reasoning). |
Use model=None, base_url=None, api_key=None, backend="openai-compatible", name=None as the inputs for this operation.
Factory for an LLM handle (same as constructing # llm). Env fallbacks apply inside the constructor. Optional name= tags the handle (fast / reasoning).
We retain h = [Llm](llm(model=model, base_url=base_url, api_key=api_key, backend=backend, name=name)).
Return h.
fast
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named small/fast handle. Model from arg, else MARQDO_LLM_FAST_MODEL, else default create model. |
Use model=None, base_url=None, api_key=None as the inputs for this operation.
Named small/fast handle. Model from arg, else MARQDO_LLM_FAST_MODEL, else default create model.
modelWe retain mdl =model.-
We retain mdl = Env get.
Return [Create](create(model=mdl, base_url=base_url, api_key=api_key, name="fast", backend="openai-compatible")).
reasoning
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named strong/reasoning handle. Model from arg, else MARQDO_LLM_REASONING_MODEL, else default create model. |
Use model=None, base_url=None, api_key=None as the inputs for this operation.
Named strong/reasoning handle. Model from arg, else MARQDO_LLM_REASONING_MODEL, else default create model.
modelWe retain mdl =model.-
We retain mdl = Env get.
Return [Create](create(model=mdl, base_url=base_url, api_key=api_key, name="reasoning", backend="openai-compatible")).
prompt_body
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | any | required | Prompt source or source-reference value |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | If src starts with YAML frontmatter declaring type: prompt / 类型: 提示, return the body after the closing ---; otherwise return src unchanged. |
Use src as the inputs for this operation.
If src starts with YAML frontmatter declaring type: prompt / 类型: 提示, return the body after the closing ---; otherwise return src unchanged.
We retain sw = [Starts with](text.starts_with(text=src, prefix="---")).
- not
swReturn src. -
We retain parts = [Split](split(value=src, sep="\n---\n")).
We retain n = Len.
n< 2 Return src.-
We retain **`fm` = [At](at(value=`parts`, index=0))**.
We retain **`is_p` = [Contains](text.contains(text=`fm`, sub="type: prompt"))**.
1. not `is_p`
We retain **`is_p` = [Contains](text.contains(text=`fm`, sub="类型: 提示"))**.
2. *
**_ = 1**
1. `is_p`
We retain **`body` = [At](at(value=`parts`, index=1))**.
Return *[Str trim](text.str_trim(s=`body`))*.
2. *
Return *src*.
prompt_load
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load a prompt artifact (.mq.md / .md) from disk for ask. |
Use path as the inputs for this operation.
Load a prompt artifact (.mq.md / .md) from disk for ask.
We retain raw = Read UTF-8 text from the selected file.
Return Prompt body.
prompt
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| text | any | None | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Prompt artifact helper: path= loads a file; text= strips type: prompt frontmatter from an in-memory string. |
Use path=None, text=None as the inputs for this operation.
Prompt artifact helper: path= loads a file; text= strips type: prompt frontmatter from an in-memory string.
pathReturn Prompt load.textReturn Prompt body.-
We [Print the prepared message](print(text="ext/ai/llm.prompt: pass", path="or", text="")). We End this run with the selected exit status.
ask
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Module convenience: create a default handle and return answer text. Pass path= to load a prompt document, prompt= text, or omit both to use the entry .mq.md as a prompt artifact (type: prompt body via sys.module_source). |
Use prompt=None, path=None, model=None, base_url=None, api_key=None as the inputs for this operation.
Module convenience: create a default handle and return answer text. Pass path= to load a prompt document, prompt= text, or omit both to use the entry .mq.md as a prompt artifact (type: prompt body via sys.module_source).
We retain p = prompt.
pathWe retainp= Prompt load.promptWe retain p =prompt.-
We retain raw = Module source.
- not
rawWe [Print the prepared message](print(text="ext/ai/llm.ask: pass", prompt="or", path="(or run a prompt document as entry)")). We End this run with the selected exit status. -
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
We retain m = [Create](create(model=model, base_url=base_url, api_key=api_key)).
We retain r = Ask.
We retain _ret = [Read the text field](json.get(value=r, key="text")).
Return _ret.
llm
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| backend | any | "openai-compatible" | Configured execution or provider backend |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | LLM handle — intelligence primitive, not an HTTP client. Resolution: explicit args → entry-scope / Artifact Metadata (sys.meta_get) → sys.env_get → defaults. Prefer declaring model / api_key / base_url in frontmatter Binding, then use the lifted names. |
Use model=None, base_url=None, api_key=None, backend="openai-compatible", name=None as the inputs for this operation.
LLM handle — intelligence primitive, not an HTTP client.
Resolution: explicit args → entry-scope / Artifact Metadata (sys.meta_get) → sys.env_get → defaults.
Prefer declaring model / api_key / base_url in frontmatter Binding, then use the lifted names.
api_keyWe retain key =api_key.-
We retain key = Meta get.
**_ = 1**
backend== ollama- not
keyWe retain key = "ollama". -
**_ = 1**
- not
keyWe [Print the prepared message](print(text="ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key= / metadata api_key)")). We End this run with the selected exit status. -
_ = 1
base_urlWe retain url =base_url.-
We retain url = Meta get.
url_ = 1backend== ollama We retainurl= Env get. 1. noturlWe retain url = "http://127.0.0.1:11434/v1". 2. * _ = 1-
We retain **`url` = [Env get](sys.env_get(name="OPENAI_BASE_URL"))**.
1. not `url`
We retain **`url` = [Env get](sys.env_get(name="MARQDO_LLM_BASE_URL"))**.
2. *
**_ = 1**
1. not `url`
We retain **url = "https://api.openai.com/v1"**.
2. *
**_ = 1**
modelWe retain mdl =model.-
We retain mdl = Meta get.
mdl_ = 1-
We retain **`mdl` = [Env get](sys.env_get(name="OPENAI_MODEL"))**.
1. not `mdl`
We retain **`mdl` = [Env get](sys.env_get(name="MARQDO_LLM_MODEL"))**.
2. *
**_ = 1**
1. not `mdl`
1. `backend` == ollama
We retain **mdl = "llama3.2"**.
2. *
We retain **mdl = "gpt-4o-mini"**.
2. *
**_ = 1**
nameWe retain nm =name.-
We retain nm = None.
h =
| _type | backend | api_key | base_url | model | suffix | bearer | name |
|---|---|---|---|---|---|---|---|
| llm | backend |
key |
url |
mdl |
/chat/completions | "Bearer " | nm |
Return h.
ask
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| messages | any | None | Ordered chat message records |
| selection | any | None | Explicit runtime/model selection |
| strict_selection | any | False | Whether an unresolved selection is an error |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Semantic ask → LLMResult (text, model, finish, backend, usage, name, tool_calls). Prefer [text](result) for the answer string. Omit prompt= / path= to use the entry document (sys.module_source + prompt_body). Pass messages= for multi-turn history (M01). selection= + strict_selection=True freeze request identity without env fallback. |
Use prompt=None, path=None, messages=None, selection=None, strict_selection=False as the inputs for this operation.
Semantic ask → LLMResult (text, model, finish, backend, usage, name, tool_calls). Prefer [text](result) for the answer string. Omit prompt= / path= to use the entry document (sys.module_source + prompt_body). Pass messages= for multi-turn history (M01). selection= + strict_selection=True freeze request identity without env fallback.
We retain p = prompt.
messagesWe retain p = None.pathWe retainp= Prompt load.promptWe retain p =prompt.-
We retain raw = Module source.
- not
rawWe retain p = "". -
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
We retain pack = [Complete result](self.complete_result(prompt=p, messages=messages, selection=selection, strict_selection=strict_selection, stream=False, echo=False)).
We retain text = [Read the text field](json.get(value=pack, key="text")).
We retain usage = [Read the usage field](json.get(value=pack, key="usage")).
We retain finish = [Read the finish field](json.get(value=pack, key="finish")).
We retain err = [Read the error field](json.get(value=pack, key="error")).
We retain tc = [Read the tool_calls field](json.get(value=pack, key="tool_calls")).
- not
tcWe retaintc= Empty list. -
_ = 1
- not
textWe retain text = "". -
_ = 1
- not
finish errWe retain finish = "error".-
We retain **finish = "stop"**.
_ = 1
Hoist receiver fields before the result table — table cells can shadow self /
column names (model, usage), so [model](self) / [total_tokens](usage)
inside the table is unsafe.
We retain mdl = [Read the model field](json.get(value=self, key="model")).
We retain b = [Read the backend field](json.get(value=self, key="backend")).
We retain nm = [Read the name field](json.get(value=self, key="name")).
usageWe retaintt= [Read the total_tokens field](json.get(value=usage, key="total_tokens")). We retainustate= [Read the usage_state field](json.get(value=usage, key="usage_state")).-
We retain tt = None. We retain ustate = "unknown".
ustate== "unknown" Keep null — never coerce missing usage to zero tokens (M02 / F04). We retain tt = None.- not
ttWe retain tt = None. -
_ = 1
errWe retain calls = 0.-
We retain calls = 1.
result =
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error | selection |
|---|---|---|---|---|---|---|---|---|---|---|
text |
mdl |
finish |
b |
usage |
nm |
calls |
tt |
tc |
err |
selection |
Return result.
stream
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Semantic stream: return the event list (use llm.collect to reduce to text). Omit prompt= / path= to use the entry document. |
Use prompt=None, path=None, echo=False, stream_kind="delta" as the inputs for this operation.
Semantic stream: return the event list (use llm.collect to reduce to text). Omit prompt= / path= to use the entry document.
stream_kind=plan tags EventBus frames for the parent plan protocol (process trail).
pathWe retainp= Prompt load.promptWe retain p =prompt.-
We retain raw = Module source.
- not
rawWe retain p = "". -
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
Return [Complete](self.complete(prompt=p, stream=True, echo=echo, stream_kind=stream_kind)).
complete_result
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| messages | any | None | Ordered chat message records |
| selection | any | None | Explicit runtime/model selection |
| strict_selection | any | False | Whether an unresolved selection is an error |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Transport pack via ext/ai/llm/openai (Ollama uses the same OpenAI-compatible path). Non-stream → {text,usage,finish}; stream → {events}. Prefer messages= for multi-turn; optional selection= (ModelSelectionV1) with strict_selection=True for request-scoped identity (M01). |
Use prompt=None, messages=None, selection=None, strict_selection=False, stream=False, echo=False, stream_kind="delta" as the inputs for this operation.
Transport pack via ext/ai/llm/openai (Ollama uses the same OpenAI-compatible path). Non-stream → {text,usage,finish}; stream → {events}. Prefer messages= for multi-turn; optional selection= (ModelSelectionV1) with strict_selection=True for request-scoped identity (M01).
Return Chat completions), api_key=api_key), model=model), prompt=prompt, messages=messages, selection=selection, strict_selection=strict_selection, stream=stream, echo=echo, stream_kind=stream_kind, suffix=suffix), bearer=bearer))).
complete
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Internal / compatibility primitive. Prefer ask / stream in new code. |
Use prompt, stream=False, echo=False, stream_kind="delta" as the inputs for this operation.
Internal / compatibility primitive. Prefer ask / stream in new code.
streamWe retainpack= [Complete result](self.complete_result(prompt=prompt, stream=True, echo=echo, stream_kind=stream_kind)). We retain_ret= [Read the events field](json.get(value=pack, key="events")). Return _ret.-
We retain pack = [Complete result](self.complete_result(prompt=prompt, stream=False, echo=echo, stream_kind=stream_kind)).
We retain _ret = [Read the text field](json.get(value=pack, key="text")).
Return _ret.
chat
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Alias for complete (compat). |
Use prompt, stream=False, echo=False, stream_kind="delta" as the inputs for this operation.
Alias for complete (compat).
Return [Complete](self.complete(prompt=prompt, stream=stream, echo=echo, stream_kind=stream_kind)).