wuyang/zk-data-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: use a single agent model path

Browse Source
This commit is contained in:
wuyang
2026-07-26 18:50:51 +08:00
parent 2e8e81c790
commit d95d06233f
23 changed files with 330 additions and 454 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+15 -27
View File
@@ -1,25 +1,12 @@
# Architecture
## Product modes
## Single Agent path
Chat and Work share the same authenticated user, conversation history, and
workspace, but not the same Agent loop.
Open WebUI owns authenticated users, conversation history, and rendering.
Every normal model request is delegated to the K1412 Runtime. There is no
second Chat loop and no per-conversation mode state.
| Concern | Chat | Work |
| --- | --- | --- |
| Primary purpose | Fast conversation | Multi-step deliverables |
| Loop owner | Open WebUI native loop | K1412 Agent Runtime |
| Tools | Workspace Gateway through OpenAPI | Workspace Gateway through Runtime |
| Visible history | Open WebUI | Open WebUI |
| Run events | Open WebUI | Runtime event store |
| Context and memory | Open WebUI defaults are disabled by policy | Runtime policy and store |
| Workspace files | Authenticated K1412 file browser | Same file browser and volume |
Selecting Work atomically upgrades `(user_id, chat_id)` in the Runtime store.
Subsequent Chat requests for that conversation are rejected even if a client
tries to bypass the disabled UI control.
## Work loop
## Agent loop
The first strategy is intentionally modular:
@@ -27,21 +14,22 @@ The first strategy is intentionally modular:
- `ContextPolicy` owns visible-message cleanup and compaction.
- `ToolRegistry` owns tool schemas and dispatch.
- `AgentLoop` owns iteration, safe parallel scheduling, and delegation.
- `RuntimeStore` owns modes, events, plans, and durable Work memory.
- `RuntimeStore` owns events, plans, and durable Agent memory.
- `ExecutionProvider` owns local or SSH Docker execution.
Every run records its model tier, strategy version, scheduler version, context
Every run records its model ID, strategy version, scheduler version, context
policy, model/tool events, failures, and completion. This event stream is the
foundation for replay, evaluation, and future experiment assignment.
The light, medium, and high tiers use the internal K1412 model endpoint. The
extreme tier uses DeepSeek V4 Pro with thinking enabled and maximum reasoning
effort. Provider selection and credentials remain server-side. Thinking state
is preserved across tool turns because DeepSeek requires the assistant's
`reasoning_content` to be returned with the following tool results; Work never
publishes that hidden state as its own user-facing reasoning.
Luna, Terra, and Sol are three independent Ollama models. Each advertises
boolean thinking support, but none advertises adjustable reasoning effort.
DeepSeek V4 Pro is a fourth model configured with thinking enabled and maximum
reasoning effort. Provider selection and credentials remain server-side.
Thinking state is preserved across tool turns when the provider requires the
assistant's `reasoning_content` to be returned with following tool results.
The Agent never publishes hidden reasoning as its own user-facing output.
Work completion is evidence-gated. Requests for scripts, reports, code, or
Completion is evidence-gated. Requests for scripts, reports, code, or
other concrete artifacts are not accepted as complete until a file mutation
has succeeded and a later read, diff, or command has verified the latest
mutation. Bare interactive shell commands are rejected. If the iteration
docs/infrastructure.md
+4 -3
View File
@@ -27,6 +27,7 @@ them does not change the Agent loop:
| k1412 homepage | Service discovery entry |
| Tailscale | Private NAS-to-execution-host network |
| Unraid Compose Manager | Application lifecycle on the NAS |
| Ollama + 32 GB NVIDIA GPU | Luna, Terra, and Sol model serving |
Other NAS applications are independent tenants. They are not dependencies of
K1412 Agent merely because they share the host.
@@ -35,8 +36,8 @@ K1412 Agent merely because they share the host.
| Container | Responsibility | Agent core? |
| --- | --- | --- |
| `k1412-agent-web` | Open WebUI auth, RBAC, history, UI, Chat loop | Product shell |
| `k1412-agent-runtime` | Work loop and provider gateway | Yes |
| `k1412-agent-web` | Open WebUI auth, RBAC, history, and UI | Product shell |
| `k1412-agent-runtime` | Agent loop and provider gateway | Yes |
| `k1412-agent-gateway` | Identity, execution policy, workspace lifecycle | Yes |
| `k1412-agent-postgres` | Open WebUI and Runtime durable state | State |
| `k1412-agent-redis` | Open WebUI coordination/cache | State |
@@ -68,7 +69,7 @@ The code intended for continuous experimentation is:
- `agent_platform/runtime/loop.py`: loop and evidence policy;
- `agent_platform/runtime/context.py`: context policy;
- `agent_platform/runtime/tools.py`: tools and scheduling metadata;
- `agent_platform/store.py`: events, plans, mode state, memory;
- `agent_platform/store.py`: events, plans, and memory;
- `agent_platform/gateway/`: isolated execution providers.
Frontend branding, reverse proxy configuration, and registry automation are
docs/openwebui-integration.md
+9 -10
View File
@@ -3,14 +3,13 @@
## Responsibility split
Open WebUI is the product shell. It owns account registration, login sessions,
RBAC, administrator approval, conversation history, rendering, and the Chat
mode Agent loop. K1412 does not fork those responsibilities into a second
authentication or chat database.
RBAC, administrator approval, conversation history, and rendering. K1412 does
not fork those responsibilities into a second authentication or chat database.
K1412 Runtime owns Work mode: context selection, durable Work memory, planning,
tool schemas, scheduling, parallel reads, child Agents, evidence gating,
experiments, and run-event persistence. Workspace Gateway owns identity-bound
execution policy and Docker lifecycle.
K1412 Runtime owns the only user-facing Agent loop: context selection, durable
memory, planning, tool schemas, scheduling, parallel reads, child Agents,
evidence gating, experiments, and run-event persistence. Workspace Gateway
owns identity-bound execution policy and Docker lifecycle.
This split makes the expensive experimental surface small. A new scheduler or
context policy changes Runtime, not the account system or entire frontend.
@@ -19,7 +18,7 @@ context policy changes Runtime, not the account system or entire frontend.
Open WebUI natively understands tool-call and reasoning detail blocks. It also
has a richer live status mechanism for loops that execute inside its own
backend. Work is an external OpenAI-compatible provider, so it cannot mutate
backend. K1412 Runtime is an external OpenAI-compatible provider, so it cannot mutate
Open WebUI's internal socket status objects directly.
K1412 therefore emits Open WebUI-compatible completed tool detail blocks. Each
@@ -52,8 +51,8 @@ Upgrading Open WebUI requires:
1. updating the tag and commit pin;
2. replaying every patch with `git apply`;
3. building the Svelte production bundle;
4. running authentication, Chat, Work, and file-browser E2E tests;
4. running authentication, Agent-loop, isolation, and file-browser E2E tests;
5. reviewing upstream license changes.
The K1412 Agent loop is not embedded into Open WebUI, so most Work experiments
The K1412 Agent loop is not embedded into Open WebUI, so most Agent experiments
do not incur this upgrade cost.
docs/operations.md
+27 -4
View File
@@ -41,12 +41,35 @@ proxy.
Set `DEEPSEEK_API_BASE_URL=https://api.deepseek.com` and place
`DEEPSEEK_API_KEY` only in the protected deployment `.env`. The key is used
only by Runtime for the extreme tier and must never be added to a browser,
only by Runtime for DeepSeek V4 Pro and must never be added to a browser,
Compose file, image, repository, or log.
The SSH override removes `/var/run/docker.sock` from Gateway and mounts the
dedicated SSH directory read-only at `/root/.ssh`.
## Ollama model residency
The NAS Ollama service keeps Luna, Terra, and Sol resident with:
- `OLLAMA_KEEP_ALIVE=-1`;
- `OLLAMA_MAX_LOADED_MODELS=3`;
- `OLLAMA_NUM_PARALLEL=1`;
- `OLLAMA_GPU_OVERHEAD=2147483648`;
- Flash Attention and `q8_0` KV cache enabled.
The three 32K-context runners were measured at approximately 2.88 GB, 4.12 GB,
and 18.44 GB of GPU allocation respectively. Their combined allocation is
about 25.44 GB on the 32 GB GPU. Do not increase context size or per-model
parallelism without repeating the simultaneous-load test and leaving capacity
for inference overhead.
The persistent Unraid template is
`/boot/config/plugins/dockerMan/templates-user/my-ollama.xml`. A locked,
idempotent five-minute check in
`/boot/config/plugins/dynamix/k1412-ollama.cron` prewarms only missing models
after a host or container restart. Confirm `/api/ps` lists all three with an
infinite expiry after recovery.
## Workspace migration
Before changing execution hosts:
@@ -78,9 +101,9 @@ RUN_DOCKER_INTEGRATION=1 .venv/bin/pytest tests/test_docker_workspace.py
Production smoke checks must cover:
- anonymous requests are redirected/rejected;
- an approved user can use Chat;
- Chat can upgrade to Work but cannot downgrade;
- Work creates and verifies a real file;
- an approved user sees exactly four Agent models;
- each model routes through the custom Agent loop;
- the Agent creates and verifies a real file;
- the file browser lists and downloads that file;
- a second user cannot see it;
- Gateway health reports `ssh-docker`;