flowstate-evolve

What it is

A Python analysis tool that ingests scored execution traces from Flowstate-based agents, identifies state-level failures and regressions, and recommends specific graph modifications (such as splitting states or adding guards) without auto-promoting changes.

Features

• Converts scored workflow traces into state-level evidence groups
• Detects repeated failures, regressions, and response smells
• Recommends actions: refine_state, add_guard, split_state, merge_states
• Generates auditable old-vs-new scorecard comparisons
• Produces candidate YAML files with evolution metadata

Quickstart

cd ~/src/flowstate-evolve
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/flowstate-evolve --help

Architecture

flowchart TD
    A[Flowstate Core Runtime] -->|Executes YAML Flows| B(Reference App e.g. phone-agent-scheduler)
    B -->|Exports Scored Pass JSON| C{flowstate-evolve CLI}
    C -->|import-phone-pass| D[Evidence Normalizer]
    D -->|Writes JSONL| E[(Evidence Store)]
    C -->|analyze| F[Analyzer Engine]
    F -->|Reads| A
    F -->|Reads| E
    F -->|Generates| G[State Evolution Report]
    F -->|Generates| H[Candidate YAML]
    C -->|compare| I[Compare Engine]
    I -->|Reads| J[Old Pass JSON]
    I -->|Reads| K[New Pass JSON]
    I -->|Outputs| L[Scorecard Diff]

How it's built

Built in Python using a src-layout. It uses `yaml` to parse workflow definitions and `json` for trace data. The core logic resides in `analyzer.py` for evidence grouping and action recommendation, `compare.py` for metric diffing, and `evidence.py` for normalizing external pass files into a standard JSONL contract. CLI entry points are managed via `argparse` in `cli.py`.

How it runs

sequenceDiagram
    participant User
    participant CLI as flowstate-evolve CLI
    participant Analyzer as analyzer.py
    participant Evidence as evidence.py
    participant FS as Flowstate YAML

    User->>CLI: run analyze --flow flow.yaml --passes ./data
    CLI->>Evidence: phone_pass_to_evidence(pass_files)
    Evidence-->>CLI: normalized JSONL records
    CLI->>Analyzer: analyze(flow_yaml, evidence_records)
    Analyzer->>FS: parse workflow structure
    Analyzer->>Analyzer: group evidence by state/transition
    Analyzer->>Analyzer: detect smells & fact tags
    Analyzer->>Analyzer: recommend actions (split/merge/guard)
    Analyzer-->>CLI: state_evolution_report.json
    Analyzer-->>CLI: flow.candidate.yaml
    CLI-->>User: output files written

How to apply & reuse

Use this package after running a Flowstate agent (like phone-agent-scheduler) to generate evaluation passes. Run the import command to normalize raw pass JSONs into evidence JSONL, then run the analyze command against your workflow YAML to get a report of recommended changes and a candidate YAML file.

At a glance