{"id":50968340,"url":"https://github.com/ezzcodeezzlife/harness-one","last_synced_at":"2026-06-21T01:01:10.076Z","repository":{"id":364750265,"uuid":"1269080174","full_name":"ezzcodeezzlife/harness-one","owner":"ezzcodeezzlife","description":"A minimal fractal task-decomposition harness for local LLMs via Ollama","archived":false,"fork":false,"pushed_at":"2026-06-14T09:38:38.000Z","size":82,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-14T11:21:57.973Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ezzcodeezzlife.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T09:33:34.000Z","updated_at":"2026-06-14T09:38:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ezzcodeezzlife/harness-one","commit_stats":null,"previous_names":["ezzcodeezzlife/harness-one"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ezzcodeezzlife/harness-one","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezzcodeezzlife%2Fharness-one","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezzcodeezzlife%2Fharness-one/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezzcodeezzlife%2Fharness-one/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezzcodeezzlife%2Fharness-one/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ezzcodeezzlife","download_url":"https://codeload.github.com/ezzcodeezzlife/harness-one/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezzcodeezzlife%2Fharness-one/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34510287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-18T23:01:42.667Z","updated_at":"2026-06-18T23:01:45.939Z","avatar_url":"https://github.com/ezzcodeezzlife.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# harness-one — a fractal task-decomposition harness\n\nA minimal, dependency-free Python harness that lets a local LLM tackle tasks far\nlarger than its context window, by treating the context window as **RAM** (loaded\nand flushed deliberately) and keeping the real state on disk.\n\n![The live web UI — a task tree building in real time](ui_shot.png)\n\n*The web visualizer: each node is a subtask coloured by state (planning → running\n→ synthesizing → done), solid edges are parent→child, dashed edges are real\ndependencies, and the live event log streams below.*\n\nOne recursive `Node` type is used identically at every level:\n\n```\nrun_node(task):\n    plan = decide(task)          # one LLM call\n    if plan is atomic:           # LEAF\n        return do(task)          # produce the deliverable + a compact summary\n    else:                        # BRANCH\n        children = plan.subtasks # wired as a DAG (edge = ordering, none = parallel)\n        run children (parallel where no edge, respecting dependencies)\n        return synthesize(children)   # assemble full child outputs -\u003e result\n```\n\nBecause the interface is identical, a branch orchestrating its children runs the\n**same code** as the root orchestrating the whole job. It's self-similar all the\nway down — fractal.\n\n## Why it works (the design in one breath)\n\n- **Externalized state.** The on-disk run directory (`runs/\u003cid\u003e/`) is the source\n  of truth, not the message history. Nodes hold a compact summary + a pointer to\n  their full artifact on disk.\n- **DAG, not a list.** Children declare `depends_on`. Independent children run\n  concurrently; dependents wait. Sequential vs parallel is just \"is there an\n  edge?\". A topological, event-driven scheduler walks it.\n- **Compaction over overflow.** Anything that aggregates content (synthesis,\n  dependency context) is checked against the window *before* the call. If it\n  would overflow, it is folded (map-reduce summarize) and oversized pieces are\n  recursively summarized — never blindly truncated.\n- **Retrieval over compression.** Synthesis pulls children's *full* outputs from\n  the store to assemble the real deliverable; the compact summary is only what\n  bubbles up to the grandparent.\n- **Graceful degradation.** Decomposability gate (don't split what's atomic),\n  depth cap, dependency-cycle breaking, partial-failure tolerance (a branch\n  synthesizes from whatever subtasks succeeded), and planning-failure fallback\n  (degrade to a direct attempt).\n\nThe honest limit (see it fail *loudly*, not silently): this is divide-and-conquer\nfor cognition. It extracts all the modularity a task *has*; it cannot create\nmodularity that isn't there. Densely-coupled tasks don't factor, and summaries\nof them are lossy — that wall is a property of the task, not the harness.\n\n## Requirements\n\n- Python 3.9+ (tested on 3.14). **No pip packages** — stdlib only.\n- [Ollama](https://ollama.com) running locally with a model pulled:\n  ```\n  ollama pull qwen2.5:7b-instruct      # fast, good default\n  ollama pull qwen2.5:14b-instruct     # cleaner decomposition, slower\n  ```\n  `qwen2.5` is used because it is reliable at structured (JSON) output and\n  distinguishing real data-dependencies from mere temporal order.\n\n## Use it\n\nCLI:\n\n```\npython run.py \"your big task here\"\npython run.py \"...\" --max-depth 3 --max-subtasks 8 --concurrency 4 --verbose\npython run.py \"...\" --model qwen2.5:14b-instruct --num-ctx 8192\npython run.py --resume run-20260614-020133        # resume an existing run\npython report.py                                   # scorecard for the last run\n```\n\nWeb UI (live visualizer):\n\n```\npython serve.py        # open http://localhost:8765\n```\n\nType a task, pick a model and limits, hit **Run**, and watch the tree build live:\nnodes change colour through `planning → running/waiting → synthesizing → done`,\nsolid edges are parent→child, dashed purple edges are real dependencies, and\nclicking a node shows its task, planner reasoning, summary, full output and\ntokens. The bottom pane streams the live event log over Server-Sent Events.\n\n## Layout\n\n```\nharness/\n  llm.py        Ollama HTTP client (urllib), token accounting, JSON-mode + retries\n  store.py      on-disk state store (source of truth), atomic writes, snapshots\n  context.py    token estimation + budget packing for compaction\n  prompts.py    planner / worker / synthesizer / compactor prompts + schemas\n  harness.py    the recursive node: plan, leaf, branch, DAG scheduler, compaction\n  events.py     thread-safe pub/sub for the live UI\nrun.py          CLI entry point\nserve.py        web UI server (stdlib http.server + SSE)\nreport.py       per-run quality scorecard\nweb/index.html  single-file visualizer (vanilla JS + SVG)\nruns/           per-run artifacts (the on-disk task tree)\n```\n\n## Tuning notes\n\n- `--max-subtasks` is the coverage knob: if a \"comprehensive\" task is missing\n  areas, the planner proposed more subtasks than the cap and they were dropped\n  (this is logged, not silent). Raise it.\n- `--max-depth` bounds recursion; depth is otherwise emergent (the gate stops\n  splitting once a subtask is atomic).\n- `--concurrency` caps simultaneous LLM calls. On a single local GPU the model\n  serializes anyway, so the speedup from parallel branches is modest locally but\n  real against a hosted API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezzcodeezzlife%2Fharness-one","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fezzcodeezzlife%2Fharness-one","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezzcodeezzlife%2Fharness-one/lists"}