mirivlad
/
ducklm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ducklm/docs/superpowers/plans/2026-05-19-ducklm-runtime.md

3.3 KiB
Raw Permalink Blame History

DuckLM Runtime Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build the first runnable DuckLM local cognitive runtime from Ducklm.md.

Architecture: FastAPI exposes WebChat and HTTP endpoints, RuntimeLoop coordinates tasks, ModelClient calls an OpenAI-compatible llama-server, and SQLite persists tasks/events/approvals/experience. Tools, skills, and memory are small adapters with clear boundaries so later stages can grow without turning the runtime into hardcoded workflow rules.

Tech Stack: Python 3.11+, FastAPI, httpx, aiosqlite, Pydantic, Jinja2, PyYAML, jsonschema, Qdrant client.

Task 1: Tests First

Files:

  • Create: tests/smoke/test_models_config.py

  • Create: tests/smoke/test_model_client.py

  • Create: tests/smoke/test_api_health.py

  • Create: tests/smoke/test_event_log.py

  • Create: tests/smoke/test_action_directive_schema.py

  • Create: tests/smoke/test_tool_gateway.py

  • Create: tests/smoke/test_approvals.py

  • Create: tests/smoke/test_skill_registry.py

  • Create: tests/smoke/test_experience_recorder.py

  • Create: tests/smoke/test_vector_memory.py

  • Write smoke tests for config, model role mapping, stores, tools, approvals, skills, experience, memory, and API health.

  • Run python -m pytest tests/smoke -v and verify tests fail because implementation modules do not exist.

Task 2: Runtime Core

Files:

  • Create: pyproject.toml

  • Create: .env.example

  • Create: config/models.yaml

  • Create: duck_core/config.py

  • Create: duck_core/model_client.py

  • Create: duck_core/events/store.py

  • Create: duck_core/tasks/store.py

  • Create: duck_core/tasks/state.py

  • Create: duck_core/context_builder.py

  • Create: duck_core/runtime_loop.py

  • Create: duck_core/api.py

  • Implement settings and model config loading.

  • Implement ModelClient role-based chat calls with latency and usage capture.

  • Implement SQLite task and event stores.

  • Implement RuntimeLoop for POST /v1/chat.

  • Implement FastAPI endpoints and WebChat rendering.

Task 3: Stage Adapters

Files:

  • Create: duck_core/tools/*

  • Create: duck_core/approvals/service.py

  • Create: duck_core/skills/registry.py

  • Create: duck_core/experience/recorder.py

  • Create: duck_core/reflection.py

  • Create: duck_core/memory/*

  • Create: duck_core/schemas/action_directive.schema.json

  • Implement safe file read/write and allowlisted shell execution.

  • Implement exact-action approval records.

  • Implement filesystem SkillRegistry.

  • Implement experience recording and skill proposal writing.

  • Implement Qdrant memory adapter with explicit embedding-disabled errors.

Task 4: Project Surface

Files:

  • Create: scripts/llama/*

  • Create: scripts/verify/*

  • Create: scripts/bench/bench_runtime.py

  • Create: duck_core/web/templates/*

  • Create: duck_core/web/static/*

  • Create: skills/analyze_project/*

  • Create: docker-compose.memory.yml

  • Create: Makefile

  • Create: README.md

  • Create: docs/*.md

  • Add llama-server scripts, verification scripts, benchmark, WebChat pages, starter skill, compose file, make targets, and docs.

  • Run smoke tests and syntax checks.