docs: add thesis outline
This commit is contained in:
@@ -10,6 +10,8 @@ implementation plans are kept for context, not as active instructions.
|
||||
and verification commands.
|
||||
- [`add/2026-06-workflow-platform-presentation.md`](add/2026-06-workflow-platform-presentation.md):
|
||||
concise presentation narrative for the current product shape and demo flow.
|
||||
- [`add/thesis-outline.md`](add/thesis-outline.md): thesis/report scaffold,
|
||||
argument structure, evidence checklist, limitations, and future work.
|
||||
- [`current_roadmap.md`](current_roadmap.md): active next-work list after the
|
||||
core type-shape cleanup.
|
||||
- [`wf_core_architecture.md`](wf_core_architecture.md): kernel package
|
||||
|
||||
@@ -0,0 +1,229 @@
|
||||
# Thesis Outline
|
||||
|
||||
This is a writing scaffold for a thesis/report about the workflow platform. It
|
||||
should guide the argument; it is not a changelog.
|
||||
|
||||
## Core Argument
|
||||
|
||||
Agent work should be represented as typed, durable workflows. The LLM should
|
||||
plan and revise workflow structure, but a deterministic runtime should own
|
||||
execution, state, validation, persistence, and source binding.
|
||||
|
||||
The short version:
|
||||
|
||||
> The LLM plans. The runtime executes. Source providers expose capabilities.
|
||||
> Stores preserve durable workflow state.
|
||||
|
||||
## 1. Problem Statement
|
||||
|
||||
Current agent/tool systems often let the LLM directly orchestrate side effects
|
||||
through ad hoc tool calls. This creates practical problems:
|
||||
|
||||
- weak validation before execution
|
||||
- poor resumability after interruption or process restart
|
||||
- hard-to-audit tool-call traces
|
||||
- limited reuse of successful procedures
|
||||
- unclear boundaries between planning, execution, and provider-specific state
|
||||
|
||||
The thesis should frame the platform as a response to those pressures.
|
||||
|
||||
## 2. Thesis
|
||||
|
||||
The proposed model is a workflow platform for AI-assisted work:
|
||||
|
||||
- workflows are typed graphs
|
||||
- source capabilities are exposed through explicit contracts
|
||||
- deployments bind logical source requirements to concrete sources
|
||||
- runs are durable stopped records
|
||||
- clients interact through stable APIs/transports rather than direct runtime
|
||||
internals
|
||||
|
||||
This is not a claim that LLMs cannot operate tools. It is a claim that durable,
|
||||
inspectable, reusable work benefits from a separate execution substrate.
|
||||
|
||||
## 3. Design Goals
|
||||
|
||||
The design goals should be stated early and then revisited in evaluation:
|
||||
|
||||
- deterministic execution
|
||||
- typed inputs, state, outputs, and node payloads
|
||||
- explicit source binding
|
||||
- durable artifacts, deployments, and stopped runs
|
||||
- inspectable trace slices
|
||||
- resumability after interruption
|
||||
- transport neutrality for CLI, server, and future UI/MCP clients
|
||||
- source-provider extensibility for MCP, Python, OpenAPI, and future families
|
||||
|
||||
## 4. Architecture
|
||||
|
||||
Explain the active package boundaries:
|
||||
|
||||
```text
|
||||
wf_cli
|
||||
-> wf_transport_rpc_http
|
||||
-> wf_server
|
||||
-> wf_api
|
||||
-> wf_core / wf_artifacts / wf_sources_*
|
||||
```
|
||||
|
||||
Important layers:
|
||||
|
||||
- `wf_core`: deterministic workflow kernel
|
||||
- `wf_authoring`: Python authoring helpers and `NodeSpec` creation
|
||||
- `wf_api`: application surface for capabilities, drafts, artifacts,
|
||||
deployments, runs, and admin/source operations
|
||||
- `wf_server`: durable server composition boundary
|
||||
- `wf_transport_rpc_http`: JSON-RPC-over-HTTP transport
|
||||
- `wf_sources_mcp`: MCP upstream source implementation and persistent runtime
|
||||
- `wf_sources_python`: trusted in-process Python source loading
|
||||
- `wf_mcp`: legacy/special-purpose MCP frontend and compatibility package
|
||||
|
||||
The thesis should explain why the old “everything in MCP” shape was split:
|
||||
transport, source provider, workflow API, and runtime concerns are different.
|
||||
|
||||
## 5. Workflow Model
|
||||
|
||||
Describe workflows as typed graphs:
|
||||
|
||||
- `input_schema`: validates run input
|
||||
- `state_schema`: defines workflow memory and reducer behavior
|
||||
- `output_schema`: defines final result shape
|
||||
- `NodeUse`: invokes named `NodeSpec`
|
||||
- edges: route by declared outcomes
|
||||
- reducers: merge concurrent or repeated writes safely
|
||||
- interrupts: represent typed external input points
|
||||
- subgraphs: compose workflows as nodes
|
||||
|
||||
Key distinction:
|
||||
|
||||
- outcome controls routing
|
||||
- output carries business data
|
||||
|
||||
## 6. Source Model
|
||||
|
||||
The common boundary is `CapabilitySource`.
|
||||
|
||||
Source families today:
|
||||
|
||||
| Source | Kind | Role |
|
||||
| --- | --- | --- |
|
||||
| `wf.std` | `system` | built-in workflow nodes and reducers |
|
||||
| `wf.recipes` | `system` | first-party workflow recipes |
|
||||
| MCP sources | `connection` | upstream MCP tools/resources/prompts |
|
||||
| Python sources | `python` | trusted project-local `NodeSpec` registries |
|
||||
|
||||
The thesis should stress that the runtime does not care where a `NodeSpec` came
|
||||
from. Source-specific behavior belongs in provider packages and server
|
||||
composition.
|
||||
|
||||
Current provider seam:
|
||||
|
||||
```python
|
||||
class WorkflowSourceProvider(Protocol):
|
||||
def load_sources(self) -> Mapping[str, CapabilitySource]: ...
|
||||
```
|
||||
|
||||
This seam is intentionally narrow: it covers static inventory, not runtime
|
||||
pools, admin/apply, auth, or live health checks.
|
||||
|
||||
## 7. Implementation Vertical Slice
|
||||
|
||||
Use the working product path as evidence:
|
||||
|
||||
```text
|
||||
wf config validate
|
||||
-> wf-rpc-server --config
|
||||
-> wf status
|
||||
-> wf source list
|
||||
-> wf cap list / inspect / call
|
||||
-> wf draft create-from-capability
|
||||
-> wf draft save
|
||||
-> wf deploy save / validate
|
||||
-> wf run start
|
||||
-> wf run inspect / trace / list
|
||||
```
|
||||
|
||||
A strong demonstration is the Python source flow:
|
||||
|
||||
1. write `ops.py` with `@node`
|
||||
2. configure `kind: "python"` source
|
||||
3. validate config
|
||||
4. start server
|
||||
5. call `local.ops.echo`
|
||||
6. create draft/artifact/deployment
|
||||
7. run deployment successfully
|
||||
|
||||
This shows the source abstraction is not MCP-only.
|
||||
|
||||
## 8. Evaluation
|
||||
|
||||
Evaluation should use concrete evidence:
|
||||
|
||||
- automated tests for workflow core, API, transports, source providers, and CLI
|
||||
- live smoke test against `wf-rpc-server`
|
||||
- durable run/resume tests
|
||||
- stateful MCP session reuse tests
|
||||
- Python source workflow-run integration test
|
||||
- config validation catching import/path errors before server startup
|
||||
|
||||
Avoid vague claims such as “robust” or “production-ready” unless backed by
|
||||
specific checks.
|
||||
|
||||
Possible evaluation questions:
|
||||
|
||||
- Can a source capability be discovered, called, saved into a workflow, deployed,
|
||||
and run?
|
||||
- Can an interrupted run survive process restart and resume?
|
||||
- Can the same server be used through CLI and JSON-RPC transport?
|
||||
- Can a new source family be added without changing `wf_core`?
|
||||
- Are large/raw provider payloads bounded in CLI output?
|
||||
|
||||
## 9. Limitations
|
||||
|
||||
State limitations explicitly:
|
||||
|
||||
- Python sources are trusted in-process code; no sandbox yet.
|
||||
- Python sources are static at server startup; no hot reload yet.
|
||||
- Source provider lifecycle is early, especially for non-MCP mutable sources.
|
||||
- File-backed stores are the proven storage backend; SQL/secret manager support
|
||||
is future work.
|
||||
- Run deletion is not implemented.
|
||||
- MCP widgets/apps are not carried through the durable workflow path.
|
||||
- Crash recovery is at stopped boundaries, not arbitrary mid-node checkpoints.
|
||||
|
||||
Limitations make the thesis more credible. They also motivate future work.
|
||||
|
||||
## 10. Future Work
|
||||
|
||||
Likely future-work sections:
|
||||
|
||||
- provider lifecycle: add/update/remove/apply/reload for multiple source families
|
||||
- OpenAPI source provider
|
||||
- Python development reload
|
||||
- production auth/secret stores
|
||||
- SQL/transactional stores
|
||||
- scheduler/server daemon operations
|
||||
- UI/admin dashboard
|
||||
- richer evaluation with real workflows and larger source catalogs
|
||||
|
||||
## What Not To Do
|
||||
|
||||
Do not make the thesis a commit history. The reader does not need every
|
||||
refactor.
|
||||
|
||||
Do not over-center MCP. MCP is one source family and one compatibility/frontend
|
||||
area, not the whole platform.
|
||||
|
||||
Do not claim unimplemented production properties:
|
||||
|
||||
- no Python sandbox
|
||||
- no general provider hot reload
|
||||
- no production secret manager
|
||||
- no full MCP widget passthrough
|
||||
|
||||
The strongest version is an honest systems argument:
|
||||
|
||||
1. Direct LLM tool orchestration has durability and validation problems.
|
||||
2. Typed workflows address those problems.
|
||||
3. The implementation proves the model across local, MCP, and Python sources.
|
||||
4. Remaining work is clear and bounded.
|
||||
Reference in New Issue
Block a user