Metadata-Version: 2.4
Name: longformops
Version: 0.1.0
Summary: Deterministic orchestration for long-form AI work
Author: Oya
License-Expression: AGPL-3.0-only
Keywords: agents,codex,long-form,orchestration,llm,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYRIGHT
Dynamic: license-file

# LongFormOps

**Deterministic orchestration for long-form AI work.**

> **Code owns state and evidence. Models produce candidates. Humans keep approval authority.**

Long-running AI workflows often fail for boring reasons: the controller keeps rereading entire documents, mutable inputs drift after a task starts, model output quietly becomes “truth,” and later nobody can prove which exact inputs produced an accepted result.

LongFormOps is a small, local-first control plane for those failure modes. It does **not** generate text by itself and it is **not** another model wrapper. It gives long-form workers—Codex, another agent system, scripts, or humans—a deterministic workflow around frozen context, provenance, approval, and binding.

[简体中文](README.zh-CN.md)

## Why LongFormOps

| Failure mode | LongFormOps response |
|---|---|
| Controller context grows without bound | Thin controller + file-based full outputs |
| Input changes after task dispatch | SHA-256-pinned immutable context capsule |
| Model calls its own output “approved” | Approval is an explicit database fact |
| Candidate output silently becomes authority | `SUBMITTED → PROMOTED → BOUND` transitions |
| Workflow template changes rewrite old projects | Project-local frozen profile + hash |
| Files and database drift apart | `longformops doctor` fails closed |
| Duplicate/partial operations leave confusing state | Duplicate guards, cleanup on failed dispatch/create, orphan detection |

The core idea is simple: **chat history is context, not a database.**

## What v0.1 provides

- local SQLite authority ledger with foreign keys and WAL;
- frozen workflow profiles bound by SHA-256 at project creation;
- immutable `CONTEXT.json` capsules with exact pinned input hashes;
- deterministic phase-level context byte budgets;
- task lifecycle: `DISPATCHED → RUNNING → SUBMITTED → PROMOTED → BOUND`;
- explicit human approval gates defined by profile;
- task-scoped artifact identity with content-addressed storage paths;
- one-time project/unit/phase binding;
- `doctor` verification for database identity, SQLite integrity, profiles, task context, pinned inputs, artifacts, bindings, and orphan authority directories;
- example profiles for fiction, research reports, and technical books;
- Codex-oriented thin-controller and worker agent examples;
- zero runtime dependencies outside the Python standard library.

## 60-second mental model

```text
workspace inputs
      │
      ▼
   DISPATCH
      │  freezes exact paths + hashes + budget
      ▼
 immutable CONTEXT.json
      │
      ▼
    worker
      │
      ▼
 candidate file
      │
      ▼
 SUBMITTED → PROMOTED
                 │
          human gate? ── yes ──► APPROVED
                 │
                 ▼
               BOUND
                 │
                 ▼
 authoritative dependency for later phases
```

A worker cannot make its own output authoritative. Later phases consume only declared **bound** dependencies.

## Quick start

Requires Python 3.11+.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .

longformops init
longformops project create DEMO --title "Demo" --profile fiction
longformops next DEMO C001
longformops task dispatch DEMO C001 plan --input examples/fiction-demo/brief.md
```

The dispatch response contains a `task_id` and immutable context path. Start the task, let a worker create a normal workspace file such as `plan.md`, then run:

```bash
longformops task start <task_id>
longformops task submit <task_id> plan.md
longformops task promote <task_id>
longformops task approve <task_id> --note "Plan approved"
longformops task bind <task_id>
longformops doctor
longformops next DEMO C001
```

For a fully mechanical demo with no model call:

```bash
make demo
```

## Profiles, not forks

A profile is ordinary TOML. It declares phase order, worker role, output kind, dependencies, approval gate, and maximum context size.

```toml
[[phases]]
id = "draft"
agent = "writer"
output_kind = "draft"
requires = ["plan", "outline"]
gate = false
max_context_bytes = 400000
```

The package ships three built-in profiles (`fiction`, `research-report`, `technical-book`), mirrored as editable TOML templates under `profiles/`. You may pass either a built-in name or an explicit TOML path to `--profile`.

A project's profile is copied into `.longformops/projects/<id>/profile.toml` and pinned by hash. Editing a template later does **not** silently rewrite existing project rules.

See [Profile authoring guide](docs/PROFILE_GUIDE.md).

## Codex integration

The repository includes `AGENTS.md`, `.codex/config.toml`, and example subagents for a thin-controller pattern. The controller inspects small state records and dispatches bounded work; workers read the current task's `CONTEXT.json` plus only the pinned files listed there; full deliverables stay in files rather than being copied back through controller chat history.

Codex is an example executor, not a dependency. See [Codex integration](docs/CODEX_INTEGRATION.md).

## Integrity model

LongFormOps fails closed when it detects conditions such as:

- partial or mismatched authority identity;
- frozen profile drift;
- changed or symlinked task context;
- changed pinned task inputs;
- context budget overflow;
- changed submitted or bound artifact bytes;
- skipped human gate;
- duplicate active task for the same project/unit/phase;
- duplicate binding;
- orphan project/task authority directories.

The project is designed to prevent accidental and agent-driven workflow corruption. It is **not** a defense against a malicious operating-system administrator with full disk access. See [Threat model](docs/THREAT_MODEL.md).

## What LongFormOps is not

LongFormOps is intentionally **not**:

- an autonomous “write my whole book/report” button;
- a prompt marketplace;
- a hosted agent platform;
- a vector database or retrieval system;
- an OS sandbox;
- a guarantee that model output is factually correct;
- a universal multi-agent framework.

It is a narrow control layer for **authoritative long-form state under bounded context**.

## Tests

```bash
python -m unittest discover -s tests -v
python -m compileall -q longformops
```

GitHub Actions runs the suite on Python 3.11, 3.12, and 3.13.

## Project status

**Alpha.** v0.1 deliberately keeps the state model small enough to audit. Explicit revision/supersession chains, tokenizer-aware budgets, retry/attempt receipts, pluggable executors, signed receipts, and richer benchmark/eval tooling are on the [roadmap](ROADMAP.md) rather than being simulated in the first release.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Core concepts](docs/CONCEPTS.md)
- [Profile guide](docs/PROFILE_GUIDE.md)
- [Codex integration](docs/CODEX_INTEGRATION.md)
- [Context and token economics](docs/TOKEN_ECONOMICS.md)
- [Threat model](docs/THREAT_MODEL.md)
- [FAQ](docs/FAQ.md)
- [Contributing](CONTRIBUTING.md)
- [Security](SECURITY.md)
- [Support](SUPPORT.md)

## Contributing

Behavior changes that affect authority semantics should start with an issue. Every state-transition or integrity change should include regression coverage. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

**AGPL-3.0-only.** See [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT).

You may use, study, modify, and redistribute this software. If you distribute a
modified version — or offer one to users over a network — you must make the
corresponding source of your modified version available under the same license.

If your organization cannot use AGPL-licensed software, see [COMMERCIAL.md](COMMERCIAL.md).

The LongFormOps name is not covered by this license. See [TRADEMARKS.md](TRADEMARKS.md).
