From d8d435feadec75284654c4faec1a34e44ba40b79 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 24 Sep 2026 19:30:25 +0800 Subject: [PATCH] feat(ai-stack): metrics, named handles, prompt docs, backends, zero-LLM MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Finish ai-stack steps 1–5: model_turn usage, fast/reasoning, type:prompt load, openai/ollama split, and agent-zero-llm gold. Fix compiled-skill Marqdo syntax so llm_free await no longer falls through to plan+HTTP. Co-authored-by: Cursor --- doc/design/ext-agent.md | 4 +- doc/design/ext-llm.md | 37 +++-- doc/roadmap/ai-stack.md | 35 +++-- ext/ai/agent.mq.md | 110 ++++++++++---- ext/ai/llm.mq.md | 217 +++++++++++++++++++-------- ext/ai/llm/ollama.mq.md | 55 +++++++ ext/ai/llm/openai.mq.md | 108 +++++++++++++ ext/ai/大模型.mq.md | 214 +++++++++++++++++--------- plugins/agent/src/kb.rs | 2 +- plugins/agent/src/memory.rs | 2 +- scripts/agent-harness.sh | 7 +- tests/ext/agent-zero-llm.mq.md | 60 ++++++++ tests/ext/fixtures/prompt-marqdo.md | 11 ++ tests/ext/fixtures/prompt-pong.mq.md | 6 + tests/ext/llm-named-offline.mq.md | 26 ++++ tests/gold.rs | 42 ++++++ 16 files changed, 738 insertions(+), 198 deletions(-) create mode 100644 ext/ai/llm/ollama.mq.md create mode 100644 ext/ai/llm/openai.mq.md create mode 100644 tests/ext/agent-zero-llm.mq.md create mode 100644 tests/ext/fixtures/prompt-marqdo.md create mode 100644 tests/ext/fixtures/prompt-pong.mq.md create mode 100644 tests/ext/llm-named-offline.mq.md diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index 79503c2..4b4c081 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -194,7 +194,9 @@ ext/ | `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 | | `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 | -**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。 +**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。 + +**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。 **Adaptive Routing(P4,原「Jev Router」更名)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(用户自备小参数模型)/ `jev`(可选)/ `llm` / `auto` 级联。**不依赖 Jev**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。 diff --git a/doc/design/ext-llm.md b/doc/design/ext-llm.md index c52ace8..b3f5edc 100644 --- a/doc/design/ext-llm.md +++ b/doc/design/ext-llm.md @@ -2,7 +2,7 @@ | | | |---|---| -| Status | **Accepted · v0.2 semantic**(005:Intelligence Primitive) | +| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) | | Date | 2026-09-24 | | Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) | @@ -11,8 +11,9 @@ `ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper. ```text -Author surface: ask / stream / collect / create -Internal: complete (compat) + openai-compatible HTTP +Author surface: ask / stream / collect / create / fast / reasoning / prompt_load +Transport: ext/ai/llm/openai.mq.md (+ ollama defaults) +Compat: complete / chat ``` Import: @@ -29,10 +30,12 @@ import llm:ext/ai/llm.mq.md |---------|---------|------| | `## load_env` | `## 加载环境` | Load `.env` | | `## create` | `## 创建` | Factory → LLM handle | -| `## ask` (module) | `## 提问` | Convenience → **text** | +| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles | +| `## prompt_load` | `## 加载提示` | Load prompt artifact (`type: prompt` → body) | +| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) | | `## collect` | `## 收集` | Events → text | | `## stream_result` | `## 流式结果` | Alias of `collect` | -| `# llm` | `# 大模型` | Handle ctor | +| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) | | `## ask` (method) | `## 提问` | → **LLMResult** map | | `## stream` | `## 流式` | → event list | | `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive | @@ -47,18 +50,25 @@ import llm:ext/ai/llm.mq.md **result = > `model`.ask prompt=`prompt`** *[text](result)* -**events = > `model`.stream prompt=`prompt`** +**fast = > llm.fast** +**events = > `fast`.stream prompt=`prompt`** **text = > llm.collect events=`events`** + +**body = > llm.prompt_load path="fixtures/prompt-marqdo.md"** ``` -### LLMResult (minimal) +### LLMResult | Field | Meaning | |-------|---------| | `text` | Answer string | | `model` | Model id | | `finish` | Finish reason (`stop`, …) | -| `backend` | e.g. `openai-compatible` | +| `backend` | e.g. `openai-compatible` / `ollama` | +| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` | +| `tokens` | Alias of `usage.total_tokens` (agent metrics) | +| `name` | Optional handle tag (`fast` / `reasoning`) | +| `llm_calls` | `1` per ask | ### Compat @@ -70,13 +80,19 @@ import llm:ext/ai/llm.mq.md OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_MODEL=gpt-4o-mini +MARQDO_LLM_FAST_MODEL=... +MARQDO_LLM_REASONING_MODEL=... +OLLAMA_HOST=http://127.0.0.1:11434/v1 ``` Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`. -## Roadmap (see ai-stack.md) +## Backends -Prompt-as-document, named models (`fast` / `reasoning`), multi-backend split, richer usage/tool_calls — deferred; keep transport behind the semantic API. +| `backend=` | Module | Notes | +|------------|--------|-------| +| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE | +| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` | ## Tests @@ -84,4 +100,5 @@ Prompt-as-document, named models (`fast` / `reasoning`), multi-backend split, ri - `tests/ext/llm-ctor-offline.mq.md` - `tests/ext/llm-ask-offline.mq.md` (create + collect) - `tests/ext/llm-stream-offline.mq.md` +- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load) - Live: `llm-complete.mq.md` · `llm-stream-live.mq.md` diff --git a/doc/roadmap/ai-stack.md b/doc/roadmap/ai-stack.md index 4d9c9b0..26f06e0 100644 --- a/doc/roadmap/ai-stack.md +++ b/doc/roadmap/ai-stack.md @@ -19,7 +19,7 @@ | **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` | | **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` | | **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) | -| **Transport** | HTTP / SSE / provider | llm 内部后端;用户不可见 | +| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 | 硬规则:`ext/**` 不调 `host_*`;agent/OKF/路由热路径只进 `plugins/agent`。 @@ -29,11 +29,11 @@ |----|------| | 语义 API:`ask` / `stream` / `collect`(`complete` 降为兼容原语) | **done** | | `create` 工厂;handle 带 `backend` | **done** | -| LLMResult:`text` / `model` / `finish` / `backend` | **done**(最小字段) | -| Prompt = Document / `llm.ask` 无参吃正文 | 暂缓 | -| Named models(`fast` / `reasoning`) | 暂缓 | -| 拆 `ext/ai/llm/openai.mq.md` 等多后端 | 暂缓 | -| usage / tool_calls 完整 Result | 暂缓 | +| LLMResult:`text` / `model` / `finish` / `backend` / `usage` / `tokens` | **done** | +| Named models(`llm.fast` / `llm.reasoning`) | **done** | +| Prompt document:`prompt_load` + `type: prompt` 正文 | **done**(`ask path=` / `llm.ask` 无参吃当前文档仍暂缓) | +| 拆 `ext/ai/llm/openai.mq.md` + `ollama` 后端 | **done** | +| tool_calls 完整 Result | 暂缓 | | Transport → 可选 ABI 插件 | 暂缓 | 作者面优先: @@ -42,6 +42,8 @@ **answer = > llm.ask prompt="What is Marqdo?"** **events = > model.stream prompt=`p`** **text = > llm.collect events=`events`** +**fast = > llm.fast** +**prompt = > llm.prompt_load path="prompts/task.md"** ``` ## 4. Agent(002–004)— 已/待 @@ -52,19 +54,20 @@ | Adaptive Routing:`marqdo` \| `small-llm` \| `jev?` \| `llm` \| `auto` | **done** | | Policy Compilation → `policies/router.mq.md` | **done** | | `run` 串联 route → execute → record → learn | **done** | -| Agent 默认走 `model.ask` + Result.usage 记成本 | 下一步 | -| Prompt artifact / document-as-prompt | 与 LLM Prompt 层一起做 | +| Agent 默认走 `model.ask` + Result.usage 记成本 | **done**(`model_turn`) | +| Prompt artifact / document-as-prompt | **done**(经 llm `path=`) | +| 零 LLM 执行(policy+skill → `llm_calls=0`) | **done** | | 真 MCP client / resume / Jev 接线 / 小模型 live 路由 | 暂缓 | -## 5. 联调顺序(继续开发) +## 5. 联调顺序 -1. **LLM Result → Agent metrics** — `step`/`plan` 记 `llm_calls`/`tokens` 从 Result 取。 -2. **Named handles** — `llm.create model=…` 命名 fast/reasoning,接到 `run router_model=`。 -3. **Prompt document** — `type: prompt` 文件 / 当前文档切片作 ask 输入。 -4. **Backend split** — openai-compatible 抽到子模块;ollama 第二后端。 -5. **Execution compilation** — policy+skill 全路径零 LLM 金样与 harness 指标。 +1. **LLM Result → Agent metrics** — **done** +2. **Named handles** — **done** +3. **Prompt document** — **done**(`type: prompt` 剥 frontmatter;无参 `ask` 仍暂缓) +4. **Backend split** — **done** +5. **Execution compilation** — **done**(`agent-zero-llm` 金样 + harness) ## 6. 验收金样 -- Agent:`tests/ext/agent-v2-learn.mq.md` · `agent-p4-route.mq.md` · `scripts/agent-harness.sh` -- LLM:`tests/ext/llm-ask-offline.mq.md` · `llm-stream-offline.mq.md` · `llm-ctor-offline.mq.md` +- Agent:`tests/ext/agent-v2-learn.mq.md` · `agent-p4-route.mq.md` · `agent-zero-llm.mq.md` · `scripts/agent-harness.sh` +- LLM:`tests/ext/llm-ask-offline.mq.md` · `llm-stream-offline.mq.md` · `llm-ctor-offline.mq.md` · `llm-named-offline.mq.md` diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 6204b20..8296697 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -49,6 +49,37 @@ The runbook `.mq.md` is ground truth (code as documentation). Default budgets ke --- +## model_turn + + `model` + + `prompt` + + `stream`=False + + `echo`=False + +One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{text,llm_calls,tokens}` for episode metrics. + +1. `stream` + **evs = > model.stream prompt=`prompt` echo=`echo`** + **text = > llm.collect events=`evs`** + **tokens = 0** +2. * + **r = > model.ask prompt=`prompt`** + **text = [text](r)** + **tokens = [tokens](r)** + 1. `tokens` + **_ = 1** + 2. * + **tokens = 0** + +`out` = + +| text | llm_calls | tokens | +|------|-----------|--------| +| `text` | 1 | `tokens` | + +*out* + +--- + ## dump_step_context + `agent` + `task`="" @@ -1264,7 +1295,7 @@ Parent Plan-and-Move prompt. Short protocol only — no long monologues. + `events` + `max_acts`=6 -LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,events}`. +LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,events,llm_calls,tokens}`. **model = > json.get value=`agent` key="model"** **last_obs = observation** @@ -1272,6 +1303,8 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event **decision = None** **last_reply = None** **evs_all = events** +**llm_calls = 0** +**tokens = 0** - `left` > 0 1. `decision` @@ -1279,11 +1312,17 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event 2. * **ctx = > build_plan_context agent=`agent` goal=`goal` observation=`last_obs` explore_attempt=`explore_attempt` explore_n=`explore_n` phase=`phase`** 1. `stream` - **evs = > model.complete prompt=`ctx` stream=True echo=`echo`** - **last_reply = > llm.stream_result events=`evs`** + **evs = > model.stream prompt=`ctx` echo=`echo`** + **last_reply = > llm.collect events=`evs`** **evs_all = > plan_merge_deltas events=`evs_all` from=`evs` stream=`stream`** + **llm_calls = llm_calls + 1** 2. * - **last_reply = > model.complete prompt=`ctx`** + **turn = > model_turn model=`model` prompt=`ctx` stream=False echo=`echo`** + **last_reply = > json.get value=`turn` key="text"** + **c = > json.get value=`turn` key="llm_calls"** + **t = > json.get value=`turn` key="tokens"** + **llm_calls = llm_calls + c** + **tokens = tokens + t** **last_reply = > trim value=`last_reply`** **act = > extract_plan_act reply=`last_reply`** **kind = > json.get value=`act` key="kind"** @@ -1314,6 +1353,8 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event **out = > json.set map=`out` key="reply" value=`last_reply`** **out = > json.set map=`out` key="observation" value=`last_obs`** **out = > json.set map=`out` key="events" value=`evs_all`** +**out = > json.set map=`out` key="llm_calls" value=`llm_calls`** +**out = > json.set map=`out` key="tokens" value=`tokens`** *out* --- @@ -1649,6 +1690,7 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o **needs_llm = > json.get value=`routed` key="needs_llm"** **exec_mode = "explore"** **llm_calls = 0** +**tokens = 0** **out = None** **route_backend = > json.get value=`routed` key="backend"** @@ -1692,13 +1734,11 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o 2. `needs_llm` 1. `router_model` **prompt = > json.get value=`routed` key="prompt"** - 1. `stream` - **evs = > router_model.complete prompt=`prompt` stream=True echo=`echo`** - **reply = > llm.stream_result events=`evs`** - 2. * - **reply = > router_model.complete prompt=`prompt`** + **turn = > model_turn model=`router_model` prompt=`prompt` stream=`stream` echo=`echo`** + **reply = > json.get value=`turn` key="text"** + **llm_calls = > json.get value=`turn` key="llm_calls"** + **tokens = > json.get value=`turn` key="tokens"** **applied = > `self`.route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`router`** - **llm_calls = 1** **am = > json.get value=`applied` key="matched"** 1. `am` **path = > json.get value=`applied` key="resource"** @@ -1791,7 +1831,7 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o 2. * **verification = "status: skipped"** -**ep = > `self`.record_episode task=`task` status=`st` result=`res` mode=`exec_mode` skill=`sk2` observation=`obs` workbook=`wb_path` cache=`cache2` match=`match2` llm_calls=`llm_calls` error=`err` memory_dir=`memory_dir`** +**ep = > `self`.record_episode task=`task` status=`st` result=`res` mode=`exec_mode` skill=`sk2` observation=`obs` workbook=`wb_path` cache=`cache2` match=`match2` llm_calls=`llm_calls` tokens=`tokens` error=`err` memory_dir=`memory_dir`** **learning = None** 1. `learn` @@ -1802,9 +1842,10 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o 2. * **_ = 1** -**execution = > json.parse text={"mode":"explore","llm_calls":0}** +**execution = > json.parse text={"mode":"explore","llm_calls":0,"tokens":0}** **execution = > json.set map=`execution` key="mode" value=`exec_mode`** **execution = > json.set map=`execution` key="llm_calls" value=`llm_calls`** +**execution = > json.set map=`execution` key="tokens" value=`tokens`** **execution = > json.set map=`execution` key="skill" value=`sk2`** **execution = > json.set map=`execution` key="router" value=`route_backend`** **out = > json.set map=`out` key="execution" value=`execution`** @@ -1841,17 +1882,20 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st **reads_left = max_reads** **reply = None** **decision = None** +**llm_calls = 0** +**tokens = 0** - `reads_left` > 0 1. `decision` **reads_left = 0** 2. * **ctx = > build_step_context agent=`self` task=`task` source_depth=`source_depth` skill_depth=`skill_depth`** - 1. `stream` - **evs = > model.complete prompt=`ctx` stream=True echo=`echo`** - **reply = > llm.stream_result events=`evs`** - 2. * - **reply = > model.complete prompt=`ctx`** + **turn = > model_turn model=`model` prompt=`ctx` stream=`stream` echo=`echo`** + **reply = > json.get value=`turn` key="text"** + **c = > json.get value=`turn` key="llm_calls"** + **t = > json.get value=`turn` key="tokens"** + **llm_calls = llm_calls + c** + **tokens = tokens + t** **reply = > trim value=`reply`** **rk = > extract_plan_read reply=`reply`** 1. `rk` == source @@ -1880,11 +1924,12 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st **task_s = > json.stringify value=`task`** **fp = "Tool CALL was rejected (not on the tools whitelist). Do NOT emit CALL. Answer the user task directly with the final answer only.\n\nUser task:\n"** **fp = fp + task_s** - 1. `stream` - **evs_retry = > model.complete prompt=`fp` stream=True echo=`echo`** - **reply = > llm.stream_result events=`evs_retry`** - 2. * - **reply = > model.complete prompt=`fp`** + **turn2 = > model_turn model=`model` prompt=`fp` stream=`stream` echo=`echo`** + **reply = > json.get value=`turn2` key="text"** + **c = > json.get value=`turn2` key="llm_calls"** + **t = > json.get value=`turn2` key="tokens"** + **llm_calls = llm_calls + c** + **tokens = tokens + t** **out = > json.set map=`out` key="status" value="ok"** **out = > json.set map=`out` key="decision" value=`decision`** **out = > json.set map=`out` key="denied_tool" value=`tool_name`** @@ -1898,17 +1943,21 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st **fp = fp + "ran via subtask and returned:"** **fp = fp + tool_s** **fp = fp + ". Reply to the user briefly."** - 1. `stream` - **evs2 = > model.complete prompt=`fp` stream=True echo=`echo`** - **reply = > llm.stream_result events=`evs2`** - 2. * - **reply = > model.complete prompt=`fp`** + **turn2 = > model_turn model=`model` prompt=`fp` stream=`stream` echo=`echo`** + **reply = > json.get value=`turn2` key="text"** + **c = > json.get value=`turn2` key="llm_calls"** + **t = > json.get value=`turn2` key="tokens"** + **llm_calls = llm_calls + c** + **tokens = tokens + t** **out = > json.set map=`out` key="tool" value=`tool_name`** **out = > json.set map=`out` key="tool_result" value=`tool_s`** **out = > json.set map=`out` key="result" value=`reply`** 2. * **out = > json.set map=`out` key="result" value=`reply`** +**out = > json.set map=`out` key="llm_calls" value=`llm_calls`** +**out = > json.set map=`out` key="tokens" value=`tokens`** + **as_turn = > json.parse text={"role":"assistant"}** **as_turn = > json.set map=`as_turn` key="content" value=`reply`** > agent_history_append id=`id` item=`as_turn` @@ -2101,11 +2150,12 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near` **soft_prompt = > build_soft_match_prompt goal=`goal` tasks=`tasks`** **model = > json.get value=`self` key="model"** 1. `stream` - **evs = > model.complete prompt=`soft_prompt` stream=True echo=`echo`** - **soft_reply = > llm.stream_result events=`evs`** + **evs = > model.stream prompt=`soft_prompt` echo=`echo`** + **soft_reply = > llm.collect events=`evs`** **events = > plan_merge_deltas events=`events` from=`evs` stream=`stream`** 2. * - **soft_reply = > model.complete prompt=`soft_prompt`** + **soft_turn = > model_turn model=`model` prompt=`soft_prompt` stream=False echo=`echo`** + **soft_reply = > json.get value=`soft_turn` key="text"** **soft_reply = > trim value=`soft_reply`** **soft_dec = > extract_plan_decision reply=`soft_reply`** **events = > plan_append_decision events=`events` decision=`soft_dec` stream=`stream`** diff --git a/ext/ai/llm.mq.md b/ext/ai/llm.mq.md index a0b5429..48d95e0 100644 --- a/ext/ai/llm.mq.md +++ b/ext/ai/llm.mq.md @@ -1,12 +1,13 @@ --- title: ext/ai/llm description: >- - Marqdo LLM intelligence primitive — ask / stream / collect. - OpenAI-compatible HTTP is an internal backend, not the authoring surface. + Marqdo LLM intelligence primitive — ask / stream / collect / named handles. + OpenAI-compatible and Ollama HTTP stay behind the semantic surface. import sys:lib/sys.mq.md -import net:lib/net.mq.md import json:lib/json.mq.md -import table:lib/table.mq.md +import fs:lib/fs.mq.md +import text:lib/text.mq.md +import openai:ext/ai/llm/openai.mq.md --- ## load_env @@ -48,27 +49,100 @@ Compatibility alias for `collect`. *> collect events=`events`* +## usage_from + + `data` + +Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map (or empty zeros). + +*> openai.usage_from data=`data`* + ## create + `model`=None + `base_url`=None + `api_key`=None + `backend`=openai-compatible + + `name`=None -Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. +Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. Optional `name=` tags the handle (`fast` / `reasoning`). -**h = > llm model=`model` base_url=`base_url` api_key=`api_key` backend=`backend`** +**h = > llm model=`model` base_url=`base_url` api_key=`api_key` backend=`backend` name=`name`** *h* -## ask - + `prompt` +## fast + `model`=None + `base_url`=None + `api_key`=None -Module convenience: create a default handle and return **answer text** (document-native one-liner). +Named small/fast handle. Model from arg, else `MARQDO_LLM_FAST_MODEL`, else default create model. + +1. `model` + **mdl = model** +2. * + **mdl = > sys.env_get name="MARQDO_LLM_FAST_MODEL"** + +*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="fast" backend="openai-compatible"* + +## reasoning + + `model`=None + + `base_url`=None + + `api_key`=None + +Named strong/reasoning handle. Model from arg, else `MARQDO_LLM_REASONING_MODEL`, else default create model. + +1. `model` + **mdl = model** +2. * + **mdl = > sys.env_get name="MARQDO_LLM_REASONING_MODEL"** + +*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="reasoning" backend="openai-compatible"* + +## prompt_load + + `path` + +Load a prompt artifact (`.mq.md` / `.md`) from disk for `ask`. +If frontmatter declares `type: prompt` (or `类型: 提示`), return the body after the closing `---`; otherwise the full file text. + +**raw = > fs.read_text path=`path`** +**sw = > text.starts_with text=`raw` prefix="---"** +1. not `sw` + *raw* +2. * + **parts = > split value=`raw` sep="\n---\n"** + **n = > len value=`parts`** + 1. `n` < 2 + *raw* + 2. * + **fm = > at value=`parts` index=0** + **is_p = > text.contains text=`fm` sub="type: prompt"** + 1. not `is_p` + **is_p = > text.contains text=`fm` sub="类型: 提示"** + 2. * + **_ = 1** + 1. `is_p` + **body = > at value=`parts` index=1** + *> text.str_trim s=`body`* + 2. * + *raw* + +## ask + + `prompt`=None + + `path`=None + + `model`=None + + `base_url`=None + + `api_key`=None + +Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, or `prompt=` text. + +1. `path` + **p = > prompt_load path=`path`** +2. `prompt` + **p = prompt** +3. * + > print text=ext/ai/llm.ask: pass prompt= or path= + > sys.exit code=1 **m = > create model=`model` base_url=`base_url` api_key=`api_key`** -**r = > m.ask prompt=`prompt`** +**r = > m.ask prompt=`p`** *[text](r)* # llm @@ -76,8 +150,9 @@ Module convenience: create a default handle and return **answer text** (document + `base_url`=None + `api_key`=None + `backend`=openai-compatible + + `name`=None -LLM handle — intelligence primitive, not an HTTP client. Transport fields stay on the handle for the openai-compatible backend only. +LLM handle — intelligence primitive, not an HTTP client. 1. `api_key` **key = api_key** @@ -88,15 +163,26 @@ LLM handle — intelligence primitive, not an HTTP client. Transport fields stay 2. * **_ = 1** -1. not `key` +1. `backend` == ollama + 1. not `key` + **key = "ollama"** + 2. * + **_ = 1** +2. not `key` > print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key=) > sys.exit code=1 -2. * +3. * **_ = 1** 1. `base_url` **url = base_url** -2. * +2. `backend` == ollama + **url = > sys.env_get name="OLLAMA_HOST"** + 1. not `url` + **url = "http://127.0.0.1:11434/v1"** + 2. * + **_ = 1** +3. * **url = > sys.env_get name="OPENAI_BASE_URL"** 1. not `url` **url = > sys.env_get name="MARQDO_LLM_BASE_URL"** @@ -116,85 +202,92 @@ LLM handle — intelligence primitive, not an HTTP client. Transport fields stay 2. * **_ = 1** 1. not `mdl` - **mdl = "gpt-4o-mini"** + 1. `backend` == ollama + **mdl = "llama3.2"** + 2. * + **mdl = "gpt-4o-mini"** 2. * **_ = 1** +1. `name` + **nm = name** +2. * + **nm = None** + `h` = -| _type | backend | api_key | base_url | model | suffix | bearer | -|-------|---------|---------|----------|-------|--------|--------| -| llm | `backend` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | +| _type | backend | api_key | base_url | model | suffix | bearer | name | +|-------|---------|---------|----------|-------|--------|--------|------| +| llm | `backend` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` | *h* ## ask - + `prompt` + + `prompt`=None + + `path`=None -Semantic ask: one-shot answer as an **LLMResult** map (`text`, `model`, `finish`, `backend`). Prefer `[text](result)` or `result` in agent metrics. +Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`). Prefer `[text](result)` for the answer string. -**text = > self.complete prompt=`prompt` stream=False echo=False** +1. `path` + **p = > prompt_load path=`path`** +2. `prompt` + **p = prompt** +3. * + > print text=ext/ai/llm: ask needs prompt= or path= + > sys.exit code=1 + +**pack = > self.complete_result prompt=`p` stream=False echo=False** +**text = > json.get value=`pack` key="text"** +**usage = > json.get value=`pack` key="usage"** +**finish = > json.get value=`pack` key="finish"** `result` = -| text | model | finish | backend | -|------|-------|--------|---------| -| `text` | [model](self) | stop | [backend](self) | +| text | model | finish | backend | usage | name | llm_calls | tokens | +|------|-------|--------|---------|-------|------|-----------|--------| +| `text` | [model](self) | `finish` | [backend](self) | `usage` | [name](self) | 1 | [total_tokens](usage) | *result* ## stream - + `prompt` + + `prompt`=None + + `path`=None + `echo`=False Semantic stream: return the event list (use `llm.collect` to reduce to text). -*> self.complete prompt=`prompt` stream=True echo=`echo`* +1. `path` + **p = > prompt_load path=`path`** +2. `prompt` + **p = prompt** +3. * + > print text=ext/ai/llm: stream needs prompt= or path= + > sys.exit code=1 + +*> self.complete prompt=`p` stream=True echo=`echo`* + +## complete_result + + `prompt` + + `stream`=False + + `echo`=False + +Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`. + +*> openai.chat_completions base_url=[base_url](self) api_key=[api_key](self) model=[model](self) prompt=`prompt` stream=`stream` echo=`echo` suffix=[suffix](self) bearer=[bearer](self)* ## complete + `prompt` + `stream`=False + `echo`=False -Internal / compatibility primitive (API-client shape). Prefer `ask` / `stream` in new code. OpenAI-compatible transport only when `backend` is openai-compatible. - -**url = [base_url](self) + [suffix](self)** -**auth = [bearer](self) + [api_key](self)** -**headers = > table.put in=None at="Authorization" value=`auth`** - -`messages` = - -| @ | role | content | -|---|------|---------| -| 1 | user | `prompt` | - -`req` = - -| model | messages | -|-------|----------| -| [model](self) | `messages` | +Internal / compatibility primitive. Prefer `ask` / `stream` in new code. 1. `stream` - **req = > table.put in=`req` at="stream" value=True** - **body = > json.stringify value=`req`** - **resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`** - 1. [status](resp) == 200 - *[events](resp)* - 2. * - > print text=ext/ai/llm: HTTP error (stream) - > print text=[status](resp) - > sys.exit code=1 + **pack = > self.complete_result prompt=`prompt` stream=True echo=`echo`** + *[events](pack)* 2. * - **body = > json.stringify value=`req`** - **resp = > net.http_post url=`url` body=`body` headers=`headers`** - 1. [status](resp) == 200 - **data = > json.parse text=[body](resp)** - *[content]([message]([1]([choices](data))))* - 2. * - > print text=ext/ai/llm: HTTP error - > print text=[status](resp) - > print text=[body](resp) - > sys.exit code=1 + **pack = > self.complete_result prompt=`prompt` stream=False echo=`echo`** + *[text](pack)* ## chat + `prompt` diff --git a/ext/ai/llm/ollama.mq.md b/ext/ai/llm/ollama.mq.md new file mode 100644 index 0000000..2866bf9 --- /dev/null +++ b/ext/ai/llm/ollama.mq.md @@ -0,0 +1,55 @@ +--- +title: ext/ai/llm/ollama +description: >- + Ollama backend defaults. Transport reuses openai-compatible /v1 chat completions. +import openai:ext/ai/llm/openai.mq.md +import sys:lib/sys.mq.md +--- + +## resolve + + `model`=None + + `base_url`=None + + `api_key`=None + +Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `ollama`, model `llama3.2`. + +1. `api_key` + **key = api_key** +2. * + **key = "ollama"** + +1. `base_url` + **url = base_url** +2. * + **url = > sys.env_get name="OLLAMA_HOST"** + 1. not `url` + **url = "http://127.0.0.1:11434/v1"** + 2. * + **_ = 1** + +1. `model` + **mdl = model** +2. * + **mdl = > sys.env_get name="MARQDO_LLM_MODEL"** + 1. not `mdl` + **mdl = "llama3.2"** + 2. * + **_ = 1** + +`cfg` = + +| backend | api_key | base_url | model | +|---------|---------|----------|-------| +| ollama | `key` | `url` | `mdl` | + +*cfg* + +## chat_completions + + `base_url` + + `api_key` + + `model` + + `prompt` + + `stream`=False + + `echo`=False + +*> openai.chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo`* diff --git a/ext/ai/llm/openai.mq.md b/ext/ai/llm/openai.mq.md new file mode 100644 index 0000000..259f87e --- /dev/null +++ b/ext/ai/llm/openai.mq.md @@ -0,0 +1,108 @@ +--- +title: ext/ai/llm/openai +description: >- + OpenAI-compatible chat completions transport (HTTP + SSE). + Used by ext/ai/llm; authors should prefer llm.ask / llm.stream. +import net:lib/net.mq.md +import json:lib/json.mq.md +import table:lib/table.mq.md +import sys:lib/sys.mq.md +--- + +## usage_from + + `data` + +Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map. + +**u = > json.get value=`data` key="usage"** +1. `u` + **pt = > json.get value=`u` key="prompt_tokens"** + **ct = > json.get value=`u` key="completion_tokens"** + **tt = > json.get value=`u` key="total_tokens"** + 1. not `pt` + **pt = 0** + 2. * + **_ = 1** + 1. not `ct` + **ct = 0** + 2. * + **_ = 1** + 1. not `tt` + **tt = pt + ct** + 2. * + **_ = 1** +2. * + **pt = 0** + **ct = 0** + **tt = 0** + +`usage` = + +| prompt_tokens | completion_tokens | total_tokens | +|---------------|-------------------|--------------| +| `pt` | `ct` | `tt` | + +*usage* + +## chat_completions + + `base_url` + + `api_key` + + `model` + + `prompt` + + `stream`=False + + `echo`=False + + `suffix`=/chat/completions + + `bearer`="Bearer " + +POST `/chat/completions` (or stream SSE). Non-stream → `{text,usage,finish}`; stream → `{events,finish}`. + +**url = base_url + suffix** +**auth = bearer + api_key** +**headers = > table.put in=None at="Authorization" value=`auth`** + +`messages` = + +| @ | role | content | +|---|------|---------| +| 1 | user | `prompt` | + +`req` = + +| model | messages | +|-------|----------| +| `model` | `messages` | + +1. `stream` + **req = > table.put in=`req` at="stream" value=True** + **body = > json.stringify value=`req`** + **resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`** + 1. [status](resp) == 200 + **pack = > json.parse text={"finish":"stop"}** + **pack = > json.set map=`pack` key="events" value=[events](resp)** + *pack* + 2. * + > print text=ext/ai/llm/openai: HTTP error (stream) + > print text=[status](resp) + > sys.exit code=1 +2. * + **body = > json.stringify value=`req`** + **resp = > net.http_post url=`url` body=`body` headers=`headers`** + 1. [status](resp) == 200 + **data = > json.parse text=[body](resp)** + **text = [content]([message]([1]([choices](data))))** + **usage = > usage_from data=`data`** + **fr = > json.get value=[1]([choices](data)) key="finish_reason"** + 1. not `fr` + **fr = "stop"** + 2. * + **_ = 1** + **pack = > json.parse text={"finish":"stop"}** + **pack = > json.set map=`pack` key="text" value=`text`** + **pack = > json.set map=`pack` key="usage" value=`usage`** + **pack = > json.set map=`pack` key="finish" value=`fr`** + *pack* + 2. * + > print text=ext/ai/llm/openai: HTTP error + > print text=[status](resp) + > print text=[body](resp) + > sys.exit code=1 diff --git a/ext/ai/大模型.mq.md b/ext/ai/大模型.mq.md index 74441c5..268b6ec 100644 --- a/ext/ai/大模型.mq.md +++ b/ext/ai/大模型.mq.md @@ -1,26 +1,23 @@ --- title: ext/ai/大模型 description: >- - Marqdo 大模型智能原语 — 提问 / 流式 / 收集。 - OpenAI 兼容 HTTP 仅为内部后端,不是编排表面。 + Marqdo 大模型智能原语 — 提问 / 流式 / 收集 / 命名句柄。 + OpenAI 兼容与 Ollama HTTP 藏在语义面之后。 导入 系统:lib/系统.mq.md -导入 网络:lib/网络.mq.md import json:lib/json.mq.md -导入 表:lib/表.mq.md +导入 文件:lib/文件.mq.md +导入 文本:lib/文本.mq.md +import openai:ext/ai/llm/openai.mq.md --- ## 加载环境 + `路径`=None -从工作目录加载 `.env`(可选 `路径=`)。不覆盖已有变量。 - *> 系统.加载环境 路径=`路径`* ## 收集 + `事件` -把流式事件列表收成最终答复文本。兼容别名:`流式结果`。 - **answer = ""** - [ev](事件) @@ -44,31 +41,91 @@ import json:lib/json.mq.md ## 流式结果 + `事件` -`收集` 的兼容别名。 - *> 收集 事件=`事件`* +## 用量 + + `数据` + +*> openai.usage_from data=`数据`* + ## 创建 + `模型`=None + `基址`=None + `密钥`=None + `后端`=openai-compatible + + `名`=None -工厂:构造大模型句柄(同 `# 大模型` 构造)。 - -**h = > 大模型 模型=`模型` 基址=`基址` 密钥=`密钥` 后端=`后端`** +**h = > 大模型 模型=`模型` 基址=`基址` 密钥=`密钥` 后端=`后端` 名=`名`** *h* -## 提问 - + `提示` +## 快速 + `模型`=None + `基址`=None + `密钥`=None -模块便捷入口:创建默认句柄并返回**答复文本**。 +1. `模型` + **mdl = 模型** +2. * + **mdl = > 系统.取环境 名="MARQDO_LLM_FAST_MODEL"** + +*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="fast" 后端="openai-compatible"* + +## 推理 + + `模型`=None + + `基址`=None + + `密钥`=None + +1. `模型` + **mdl = 模型** +2. * + **mdl = > 系统.取环境 名="MARQDO_LLM_REASONING_MODEL"** + +*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="reasoning" 后端="openai-compatible"* + +## 加载提示 + + `路径` + +加载提示文档。若 frontmatter 含 `type: prompt` / `类型: 提示`,返回闭合 `---` 后的正文。 + +**raw = > 文件.读文本 路径=`路径`** +**sw = > 文本.开头是 内容=`raw` 前缀="---"** +1. 非 `sw` + *raw* +2. * + **parts = > split value=`raw` sep="\n---\n"** + **n = > len value=`parts`** + 1. `n` < 2 + *raw* + 2. * + **fm = > at value=`parts` index=0** + **is_p = > 文本.包含 内容=`fm` 子串="type: prompt"** + 1. 非 `is_p` + **is_p = > 文本.包含 内容=`fm` 子串="类型: 提示"** + 2. * + **_ = 1** + 1. `is_p` + **body = > at value=`parts` index=1** + *> 文本.去空白 s=`body`* + 2. * + *raw* + +## 提问 + + `提示`=None + + `路径`=None + + `模型`=None + + `基址`=None + + `密钥`=None + +1. `路径` + **p = > 加载提示 路径=`路径`** +2. `提示` + **p = 提示** +3. * + > 打印 内容=ext/ai/大模型.提问: 请传 提示= 或 路径= + > 系统.退出 码=1 **m = > 创建 模型=`模型` 基址=`基址` 密钥=`密钥`** -**r = > m.提问 提示=`提示`** +**r = > m.提问 提示=`p`** *[text](r)* # 大模型 @@ -76,8 +133,7 @@ import json:lib/json.mq.md + `基址`=None + `密钥`=None + `后端`=openai-compatible - -大模型句柄 — 智能原语,不是 HTTP 客户端。 + + `名`=None 1. `密钥` **key = 密钥** @@ -88,15 +144,26 @@ import json:lib/json.mq.md 2. * **_ = 1** -1. 非 `key` - > 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY(或传入 密钥=) +1. `后端` == ollama + 1. 非 `key` + **key = "ollama"** + 2. * + **_ = 1** +2. 非 `key` + > 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY > 系统.退出 码=1 -2. * +3. * **_ = 1** 1. `基址` **url = 基址** -2. * +2. `后端` == ollama + **url = > 系统.取环境 名="OLLAMA_HOST"** + 1. 非 `url` + **url = "http://127.0.0.1:11434/v1"** + 2. * + **_ = 1** +3. * **url = > 系统.取环境 名="OPENAI_BASE_URL"** 1. 非 `url` **url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"** @@ -116,91 +183,88 @@ import json:lib/json.mq.md 2. * **_ = 1** 1. 非 `mdl` - **mdl = "gpt-4o-mini"** + 1. `后端` == ollama + **mdl = "llama3.2"** + 2. * + **mdl = "gpt-4o-mini"** 2. * **_ = 1** +1. `名` + **nm = 名** +2. * + **nm = None** + `h` = -| _type | backend | api_key | base_url | model | suffix | bearer | -|-------|---------|---------|----------|-------|--------|--------| -| 大模型 | `后端` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | +| _type | backend | api_key | base_url | model | suffix | bearer | name | +|-------|---------|---------|----------|-------|--------|--------|------| +| 大模型 | `后端` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` | *h* ## 提问 - + `提示` + + `提示`=None + + `路径`=None -语义提问:返回 **结果 map**(`text` / `model` / `finish` / `backend`)。 +1. `路径` + **p = > 加载提示 路径=`路径`** +2. `提示` + **p = 提示** +3. * + > 打印 内容=ext/ai/大模型: 提问需要 提示= 或 路径= + > 系统.退出 码=1 -**text = > 自.运行 提示=`提示` 流式=False 打印增量=False** +**pack = > 自.完整结果 提示=`p` 流式=False 打印增量=False** +**text = > json.get value=`pack` key="text"** +**usage = > json.get value=`pack` key="usage"** +**finish = > json.get value=`pack` key="finish"** `result` = -| text | model | finish | backend | -|------|-------|--------|---------| -| `text` | [model](自) | stop | [backend](自) | +| text | model | finish | backend | usage | name | llm_calls | tokens | +|------|-------|--------|---------|-------|------|-----------|--------| +| `text` | [model](自) | `finish` | [backend](自) | `usage` | [name](自) | 1 | [total_tokens](usage) | *result* ## 流式 - + `提示` + + `提示`=None + + `路径`=None + `打印增量`=False -语义流式:返回事件列表(再用 `收集` 收成文本)。 +1. `路径` + **p = > 加载提示 路径=`路径`** +2. `提示` + **p = 提示** +3. * + > 打印 内容=ext/ai/大模型: 流式需要 提示= 或 路径= + > 系统.退出 码=1 -*> 自.运行 提示=`提示` 流式=True 打印增量=`打印增量`* +*> 自.运行 提示=`p` 流式=True 打印增量=`打印增量`* + +## 完整结果 + + `提示` + + `流式`=False + + `打印增量`=False + +*> openai.chat_completions base_url=[base_url](自) api_key=[api_key](自) model=[model](自) prompt=`提示` stream=`流式` echo=`打印增量` suffix=[suffix](自) bearer=[bearer](自)* ## 运行 + `提示` + `流式`=False + `打印增量`=False -内部 / 兼容原语。新代码优先 `提问` / `流式`。 - -**url = [base_url](自) + [suffix](自)** -**auth = [bearer](自) + [api_key](自)** -**headers = > 表.改 入=None 于="Authorization" 值=`auth`** - -`messages` = - -| @ | role | content | -|---|------|---------| -| 1 | user | `提示` | - -`req` = - -| model | messages | -|-------|----------| -| [model](自) | `messages` | - 1. `流式` - **req = > 表.改 入=`req` 于="stream" 值=True** - **body = > json.stringify value=`req`** - **resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`** - 1. [status](resp) == 200 - *[events](resp)* - 2. * - > 打印 内容=ext/ai/大模型: HTTP 错误(流式) - > 打印 内容=[status](resp) - > 系统.退出 码=1 + **pack = > 自.完整结果 提示=`提示` 流式=True 打印增量=`打印增量`** + *[events](pack)* 2. * - **body = > json.stringify value=`req`** - **resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`** - 1. [status](resp) == 200 - **data = > json.parse text=[body](resp)** - *[content]([message]([1]([choices](data))))* - 2. * - > 打印 内容=ext/ai/大模型: HTTP 错误 - > 打印 内容=[status](resp) - > 打印 内容=[body](resp) - > 系统.退出 码=1 + **pack = > 自.完整结果 提示=`提示` 流式=False 打印增量=`打印增量`** + *[text](pack)* ## 聊天 + `提示` + `流式`=False + `打印增量`=False -`运行` 的别名。 - *> 自.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`* diff --git a/plugins/agent/src/kb.rs b/plugins/agent/src/kb.rs index 065c4f9..fa60e26 100644 --- a/plugins/agent/src/kb.rs +++ b/plugins/agent/src/kb.rs @@ -1269,7 +1269,7 @@ pub fn workbook_solidify(args: &Value) -> Result { }; let lit = marqdo_quoted_text(&result); let body = format!( - "---\ntitle: agent workbook\n---\n\n# main\n\n*`result` = {lit} *\n**`result`**\n" + "---\ntitle: agent workbook\n---\n\n# main\n\n**`result` = {lit}**\n*`result`*\n" ); fs::write(&p, body).map_err(|e| format!("solidify write: {e}"))?; Ok(json!({ diff --git a/plugins/agent/src/memory.rs b/plugins/agent/src/memory.rs index 814668d..f53311a 100644 --- a/plugins/agent/src/memory.rs +++ b/plugins/agent/src/memory.rs @@ -676,7 +676,7 @@ pub fn generalize(args: &Value) -> Result { fn write_compiled_mq(result: &str, title: &str) -> String { let lit = marqdo_quoted(result); format!( - "---\ntitle: {title}\ntype: skill\nstatus: compiled\nllm_free: true\n---\n\nCompiled from successful episodes (deterministic return).\n\n# main\n\n*`result` = {lit} *\n**`result`**\n" + "---\ntitle: {title}\ntype: skill\nstatus: compiled\nllm_free: true\n---\n\nCompiled from successful episodes (deterministic return).\n\n# main\n\n**`result` = {lit}**\n*`result`*\n" ) } diff --git a/scripts/agent-harness.sh b/scripts/agent-harness.sh index 6ec127f..dbc13d1 100755 --- a/scripts/agent-harness.sh +++ b/scripts/agent-harness.sh @@ -4,8 +4,10 @@ set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" MQ="${MARQDO_BIN:-$ROOT/target/release/marqdo}" -export MARQDO_EXT="${MARQDO_EXT:-$ROOT/.marqdo-ext}" -export MARQDO_AGENT_PLUGIN="${MARQDO_AGENT_PLUGIN:-$ROOT/.marqdo-ext/native/libagent.so}" +export MARQDO_EXT="${MARQDO_EXT:-$ROOT/ext}" +export MARQDO_AGENT_PLUGIN="${MARQDO_AGENT_PLUGIN:-$ROOT/target/release/libagent.so}" +# Offline golds that construct an llm handle need a dummy key (no network). +export OPENAI_API_KEY="${OPENAI_API_KEY:-sk-test}" if [[ ! -x "$MQ" ]]; then echo "missing $MQ — run: cargo build --release -p marqdo -p marqdo_plugin_agent" >&2 @@ -30,6 +32,7 @@ run tests/ext/agent-context-budget-a3.mq.md run tests/ext/agent-workbook-patch-a0.mq.md run tests/ext/agent-v2-learn.mq.md run tests/ext/agent-p4-route.mq.md +run tests/ext/agent-zero-llm.mq.md run examples/agent-okf-flywheel/index.mq.md run examples/agent-pong/index.mq.md diff --git a/tests/ext/agent-zero-llm.mq.md b/tests/ext/agent-zero-llm.mq.md new file mode 100644 index 0000000..233807e --- /dev/null +++ b/tests/ext/agent-zero-llm.mq.md @@ -0,0 +1,60 @@ +--- +title: Agent zero-LLM execution after policy/skill compile +description: After Skill+Policy compilation, run with router=marqdo records llm_calls=0. +import agent:ext/ai/agent.mq.md +import fs:lib/fs.mq.md +import json:lib/json.mq.md +import llm:ext/ai/llm.mq.md +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +# main + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=no-agent-plugin + > sys.exit code=1 + +**paths = > json.parse text={"mem":".marqdo/agent-memory-zero-llm","kb":".marqdo/agent-kb-zero-llm","task":"Reply with exactly the word pong and nothing else.","skill":"concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md"}** +**mem = > json.get value=`paths` key="mem"** +**kb = > json.get value=`paths` key="kb"** +**task = > json.get value=`paths` key="task"** +**skill = > json.get value=`paths` key="skill"** + +**ex_m = > fs.exists path=`mem`** +1. `ex_m` + > fs.remove_tree path=`mem` +2. * + **_ = 1** +**ex_k = > fs.exists path=`kb`** +1. `ex_k` + > fs.remove_tree path=`kb` +2. * + **_ = 1** +> agent_memory_ensure memory_dir=`mem` + +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 tokens=100 memory_dir=`mem`** +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 tokens=80 memory_dir=`mem`** +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=1 tokens=40 memory_dir=`mem`** +**_ = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True** +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`** +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`** +**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`** +**_ = > agent_compile_policy memory_dir=`mem` min_evidence=3** + +**model = > llm.create** +`tools` = + +| 工具 | +|------| + +**ag = > agent.agent model=`model` tools=`tools` standing="zero-llm compiled run"** +**out = > `ag`.run task=`task` kb_dir=`kb` memory_dir=`mem` learn=False router="marqdo" writeback=False** +**ex = > json.get value=`out` key="execution"** +**calls = > json.get value=`ex` key="llm_calls"** +**mode = > json.get value=`ex` key="mode"** +> print text=`mode` +> print text=`calls` diff --git a/tests/ext/fixtures/prompt-marqdo.md b/tests/ext/fixtures/prompt-marqdo.md new file mode 100644 index 0000000..0a781e5 --- /dev/null +++ b/tests/ext/fixtures/prompt-marqdo.md @@ -0,0 +1,11 @@ +--- +type: prompt +model: gpt-4o-mini +--- + +Explain Marqdo as an AI-native programming language. + +## Requirements + +- Be concise. +- Mention executable documents. diff --git a/tests/ext/fixtures/prompt-pong.mq.md b/tests/ext/fixtures/prompt-pong.mq.md new file mode 100644 index 0000000..50e56d4 --- /dev/null +++ b/tests/ext/fixtures/prompt-pong.mq.md @@ -0,0 +1,6 @@ +--- +type: prompt +title: marqdo-one-liner +--- + +Reply with exactly one English word: pong diff --git a/tests/ext/llm-named-offline.mq.md b/tests/ext/llm-named-offline.mq.md new file mode 100644 index 0000000..b600639 --- /dev/null +++ b/tests/ext/llm-named-offline.mq.md @@ -0,0 +1,26 @@ +--- +title: llm named handles + prompt_load offline +description: fast/reasoning names, ollama backend tag, and type:prompt body load; no network. +import llm:ext/ai/llm.mq.md +import text:lib/text.mq.md +--- + +# main + +**fast = > llm.fast model="qwen-fast-test"** +> print text=[name](`fast`) +> print text=[model](`fast`) + +**reason = > llm.reasoning model="gpt-reason-test"** +> print text=[name](`reason`) +> print text=[model](`reason`) + +**ollama = > llm.create backend="ollama" model="llama3.2"** +> print text=[backend](`ollama`) +> print text=[model](`ollama`) + +**prompt = > llm.prompt_load path="fixtures/prompt-marqdo.md"** +**has = > text.contains text=`prompt` sub="Explain Marqdo"** +**no_fm = > text.contains text=`prompt` sub="type: prompt"** +> print text=`has` +> print text=`no_fm` diff --git a/tests/gold.rs b/tests/gold.rs index 8a9de91..ba45927 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -3808,6 +3808,48 @@ auto/marqdo", ); } +#[test] +fn ext_agent_zero_llm() { + ensure_agent_plugin_built(); + assert_out_llm_offline( + "tests/ext/agent-zero-llm.mq.md", + "compiled +0", + ); +} + +#[test] +fn ext_llm_named_offline() { + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); + let output = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["run", "tests/ext/llm-named-offline.mq.md"]) + .env("OPENAI_API_KEY", "sk-test") + .env("MARQDO_EXT", root.join("ext")) + .env_remove("OPENAI_MODEL") + .env_remove("MARQDO_LLM_MODEL") + .env_remove("MARQDO_LLM_FAST_MODEL") + .env_remove("MARQDO_LLM_REASONING_MODEL") + .current_dir(&root) + .output() + .expect("run llm-named-offline"); + let code = output.status.code().unwrap_or(1); + let stdout = String::from_utf8_lossy(&output.stdout); + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(code, 0, "llm-named-offline stderr={stderr}"); + assert_eq!( + stdout.trim_end(), + "fast +qwen-fast-test +reasoning +gpt-reason-test +ollama +llama3.2 +True +False", + "stdout={stdout}" + ); +} + #[test] fn lib_net_encode() { assert_out("tests/lib/net-encode.mq.md", "a%20b");