Metadata-Version: 2.4
Name: flowception
Version: 0.1.0
Summary: Tools to work with flows as defined in the specification document
Author-email: eol <nullhack@users.noreply.github.com>
Maintainer-email: eol <nullhack@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026, eol
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: Repository, https://github.com/nullhack/flowception
Project-URL: Documentation, https://github.com/nullhack/flowception/tree/main/docs/api/
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pdoc>=14.0; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-beehave[html]<1,>=0.1; extra == "dev"
Requires-Dist: pytest-cov>=6.1.1; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: ruff>=0.11.5; extra == "dev"
Requires-Dist: taskipy>=1.14.1; extra == "dev"
Requires-Dist: hypothesis>=6.148.4; extra == "dev"
Requires-Dist: pyright>=1.1.407; extra == "dev"
Requires-Dist: ghp-import>=2.1.0; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="docs/assets/banner.svg" alt="flowception" width="100%"/>

<br/><br/>

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](https://nullhack.github.io/flowception/coverage/)
[![CI](https://img.shields.io/github/actions/workflow/status/nullhack/flowception/ci.yml?style=for-the-badge&label=CI)](https://github.com/nullhack/flowception/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.13-blue?style=for-the-badge)](https://www.python.org/downloads/)

**Dream it. Flow it. Go deeper.**

</div>

---

> **Beta — under active development.** The API is not yet stable. Breaking changes may occur without a major version bump until `v1.0.0` is released. Use at your own risk, and pin your dependencies.

---

Tools for defining, composing, and executing nested flows. Flowception lets you build recursive flow systems — flows within flows — where each level operates with its own context, transitions, and validation.

---

## Why flowception?

**Nested flows are hard.** Most orchestration libraries treat flows as flat sequences. When you need a sub-flow — a branch, a retry loop, a parallel task group — you either flatten it and lose clarity, or bolt on callbacks and lose composability. Flowception treats nesting as a first-class concept: a flow can contain another flow the same way a function can call another function.

**Composability over configuration.** Define flows as values, compose them declaratively, and execute them deterministically. No decorators, no metaclasses, no global state. A flow is data; execution is a function of that data.

**A totem you can trust.** Every level in a nested execution carries a validation artifact — the totem — that confirms the level completed as expected. Totems compose: the outer level's totem includes the inner level's totem, so you can verify the entire descent without replaying it.

---

## The descent

```
SCOPE → ARCH → TDD LOOP → VERIFY → ACCEPT
```

Each feature moves through five steps. At any moment, exactly one feature is in progress — enforced by filesystem state, not convention:

```
docs/features/backlog/      ← scoped, waiting
docs/features/in-progress/  ← building now (max 1)
docs/features/completed/    ← accepted and shipped
```

Scope is written before architecture. Architecture is written before code. Code is reviewed adversarially before acceptance. Nothing moves to completed without explicit Product Owner sign-off.

---

## Quick start

```bash
git clone https://github.com/nullhack/flowception
cd flowception
curl -LsSf https://astral.sh/uv/install.sh | sh  # skip if uv is already installed
uv sync --all-extras
uv run task test-fast                              # verify everything works
```

---

## Commands

| Command | Purpose |
|---------|---------|
| `uv run task test` | Full test suite with coverage |
| `uv run task test-fast` | Fast tests, no coverage (use during TDD loop) |
| `uv run task test-slow` | Slow tests only (Hypothesis property tests) |
| `uv run task lint` | Ruff format + check |
| `uv run task static-check` | Pyright type checking |
| `uv run task run` | Run the application |
| `uv run task doc-build` | Build API docs + coverage report |
| `uv run task release-check` | Pre-release validation (version, lint, types, tests, docs) |

---

## Installation

```bash
pip install flowception
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install flowception
```

---

## Versioning

Flowception uses **semver with build metadata**: `v{MAJOR}.{MINOR}.{PATCH}+{YYYYMMDD}`.

- **Patch** bump: bug fixes
- **Minor** bump: new features
- **Major** bump: breaking changes
- Same-day releases increment the patch number

Releases carry themed names following the `level-{MAJOR}.{MINOR}-{dreamworld}` convention — see [`docs/branding.md`](docs/branding.md) for details.

---

## Development standards

**TDD by default** — Red → Green → Refactor, one acceptance criterion at a time. Tests are written before the code they validate.

**Behavioural tests only** — Tests describe observable contracts, not implementation internals. A test that survives a complete internal rewrite is a good test.

**Coverage enforced** — 100% coverage threshold in `pyproject.toml`. Coverage is a floor, not a goal.

**Design principles enforced** — YAGNI, KISS, DRY, SOLID, and Object Calisthenics are review gates, not suggestions. Every principle is checked with file and line evidence before a feature is approved.

**Adversarial verification** — The architect who designed the system reviews it. The default hypothesis is "broken." Green automated checks are necessary but not sufficient for approval.

---

## Living documentation

Every artifact is version-controlled alongside the code that implements it.

| Artifact | Location | Purpose |
|----------|----------|---------|
| Feature narratives | `docs/features/` | Gherkin `.feature` files trace requirements to tests |
| Architecture decisions | `docs/adr/` | Dated ADRs preserve reasoning |
| Domain model & glossary | `docs/system.md`, `docs/glossary.md` | Shared language across team and code |
| System overview | `docs/system.md` | Reflects only completed features — no stale speculation |
| Post-mortems | `docs/post-mortem/` | Append-only failure memory |
| Branding | `docs/branding.md` | Project identity, colors, naming conventions |

---

## Contributing

This project follows a structured five-step workflow with AI-assisted development. See [`AGENTS.md`](AGENTS.md) for the full protocol, roles, and skill inventory.

---

## License

MIT — see [LICENSE](LICENSE).

**Author:** [@nullhack](https://github.com/nullhack) · [Documentation](https://nullhack.github.io/flowception)

<!-- MARKDOWN LINKS -->
[contributors-shield]: https://img.shields.io/github/contributors/nullhack/flowception.svg?style=for-the-badge
[contributors-url]: https://github.com/nullhack/flowception/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/nullhack/flowception.svg?style=for-the-badge
[forks-url]: https://github.com/nullhack/flowception/network/members
[stars-shield]: https://img.shields.io/github/stars/nullhack/flowception.svg?style=for-the-badge
[stars-url]: https://github.com/nullhack/flowception/stargazers
[issues-shield]: https://img.shields.io/github/issues/nullhack/flowception.svg?style=for-the-badge
[issues-url]: https://github.com/nullhack/flowception/issues
[license-shield]: https://img.shields.io/badge/license-MIT-green?style=for-the-badge
[license-url]: https://github.com/nullhack/flowception/blob/main/LICENSE
