fdsx 0.1.0__tar.gz

fdsx-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Publish to TestPyPI"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test
+    uses: ./.github/workflows/test.yml
+
+  build:
+    name: build
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: install build
+        run: pip install build
+      - name: build
+        run: python -m build
+      - name: upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-to-testpypi:
+    name: publish-to-testpypi
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/fdsx/
+    permissions:
+      id-token: write
+    steps:
+      - name: download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-to-pypi:
+    name: publish-to-pypi
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fdsx/
+    permissions:
+      id-token: write
+    steps:
+      - name: download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fdsx-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,53 @@
+name: test
+
+on:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: install ruff
+        run: pip install ruff
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format check
+        run: ruff format --check .
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: install dev deps
+        run: pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format check
+        run: ruff format --check .
+      - name: mypy
+        run: mypy src/fdsx
+      - name: pytest
+        run: pytest

fdsx-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

fdsx-0.1.0/AGENTS.md

@@ -0,0 +1,70 @@
+# Agent Instructions
+
+## Testing Guidelines
+
+### Test Trophy Strategy
+
+This project follows the test trophy pattern. Tests are organized into three layers:
+
+#### Directory Structure
+- `tests/unit/` — Unit tests for complex pure logic
+- `tests/integration/` — Integration tests (primary confidence layer)
+- `tests/e2e/` — CLI end-to-end tests (thinnest layer)
+
+#### What belongs at each level
+
+**Unit tests** (`tests/unit/`):
+- Complex parsing logic (YAML parsing, JSONPath resolution, variable substitution)
+- State transition rules and algorithms
+- Pure functions with non-trivial logic
+- NOT: Pydantic model field assignments, default value checks, isinstance checks
+
+**Integration tests** (`tests/integration/`):
+- Complete workflow execution via `engine.run_flow()`
+- Feature-centered tests: each file answers "Does feature X work correctly?"
+- Checkpoint persistence and recovery
+- State variable mutations and result paths
+- Tests using `CliRunner` for testing CLI behavior with mocked internals
+
+**E2E tests** (`tests/e2e/`):
+- CLI surface tests via `run_fdsx()` subprocess calls
+- Exit codes, stderr/stdout format validation
+- CLI argument parsing and mutual exclusion
+- Signal handling
+
+#### Anti-patterns to avoid
+
+- **Trivial field assertion tests**: Don't test that `TaskState(type="task").type == "task"`. Pydantic guarantees this.
+- **isinstance checks**: Don't test `isinstance(generate_thread_id(), str)`. The type system handles this.
+- **Default value tests**: Don't test that `ClaudeOptions().permission_mode is None`. This is framework behavior.
+- **Unnecessary real-time waits**: Mock `time.sleep` for in-process delays. Minimize subprocess sleep durations.
+- **Writing artifacts to project root**: Tests must never create `.fdsx/` artifacts in the project root. Always use `monkeypatch.chdir(tmp_path)` or `cwd=tmp_dir` for subprocess tests.
+
+#### Naming conventions
+
+- Test files: `test_<feature>.py` (never `test_phase1.py` or `test_e2e_phase2.py`)
+- Test functions: `test_<scenario>_<expected_outcome>`
+- Test classes: `Test<Feature><Aspect>` (e.g., `TestCheckpointResume`, `TestChoiceStateValidation`)
+
+#### Integration Test Feature-Centeredness Assessment
+
+All integration tests are already feature-centered. No files need restructuring beyond the e2e moves. Each integration test file is organized around a specific feature:
+
+- `test_checkpoint_resume.py` — checkpoint and resume behavior
+- `test_choice_flow.py` — choice state routing
+- `test_parallel_flow.py` — parallel execution
+- `test_linear_flow.py` — linear workflow execution
+- `test_loop_flow.py` — loop state behavior
+- `test_extraction_flow.py` — data extraction
+- `test_quiet_mode.py` — quiet mode flag
+- `test_result_file.py` — result file output
+- `test_resume_interrupt.py` — interrupted workflow recovery
+- `test_split.py` — batch split behavior
+- `test_tasks_dir.py` — tasks directory handling
+- `test_auto_select.py` — auto-select logic
+- `test_lock_atomicity.py` — lock file atomicity
+- `test_workflow_persistence.py` — workflow state persistence
+- `test_inactivity_timeout.py` — inactivity timeout handling
+- `test_scenario_flows.py` — cross-cutting scenario flows
+
+The integration test suite is well-organized around features (checkpoint, choice, parallel, loop, extraction, etc.) rather than implementation phases. No restructuring was required.

fdsx-0.1.0/CLAUDE.md

@@ -0,0 +1,70 @@
+# Agent Instructions
+
+## Testing Guidelines
+
+### Test Trophy Strategy
+
+This project follows the test trophy pattern. Tests are organized into three layers:
+
+#### Directory Structure
+- `tests/unit/` — Unit tests for complex pure logic
+- `tests/integration/` — Integration tests (primary confidence layer)
+- `tests/e2e/` — CLI end-to-end tests (thinnest layer)
+
+#### What belongs at each level
+
+**Unit tests** (`tests/unit/`):
+- Complex parsing logic (YAML parsing, JSONPath resolution, variable substitution)
+- State transition rules and algorithms
+- Pure functions with non-trivial logic
+- NOT: Pydantic model field assignments, default value checks, isinstance checks
+
+**Integration tests** (`tests/integration/`):
+- Complete workflow execution via `engine.run_flow()`
+- Feature-centered tests: each file answers "Does feature X work correctly?"
+- Checkpoint persistence and recovery
+- State variable mutations and result paths
+- Tests using `CliRunner` for testing CLI behavior with mocked internals
+
+**E2E tests** (`tests/e2e/`):
+- CLI surface tests via `run_fdsx()` subprocess calls
+- Exit codes, stderr/stdout format validation
+- CLI argument parsing and mutual exclusion
+- Signal handling
+
+#### Anti-patterns to avoid
+
+- **Trivial field assertion tests**: Don't test that `TaskState(type="task").type == "task"`. Pydantic guarantees this.
+- **isinstance checks**: Don't test `isinstance(generate_thread_id(), str)`. The type system handles this.
+- **Default value tests**: Don't test that `ClaudeOptions().permission_mode is None`. This is framework behavior.
+- **Unnecessary real-time waits**: Mock `time.sleep` for in-process delays. Minimize subprocess sleep durations.
+- **Writing artifacts to project root**: Tests must never create `.fdsx/` artifacts in the project root. Always use `monkeypatch.chdir(tmp_path)` or `cwd=tmp_dir` for subprocess tests.
+
+#### Naming conventions
+
+- Test files: `test_<feature>.py` (never `test_phase1.py` or `test_e2e_phase2.py`)
+- Test functions: `test_<scenario>_<expected_outcome>`
+- Test classes: `Test<Feature><Aspect>` (e.g., `TestCheckpointResume`, `TestChoiceStateValidation`)
+
+#### Integration Test Feature-Centeredness Assessment
+
+All integration tests are already feature-centered. No files need restructuring beyond the e2e moves. Each integration test file is organized around a specific feature:
+
+- `test_checkpoint_resume.py` — checkpoint and resume behavior
+- `test_choice_flow.py` — choice state routing
+- `test_parallel_flow.py` — parallel execution
+- `test_linear_flow.py` — linear workflow execution
+- `test_loop_flow.py` — loop state behavior
+- `test_extraction_flow.py` — data extraction
+- `test_quiet_mode.py` — quiet mode flag
+- `test_result_file.py` — result file output
+- `test_resume_interrupt.py` — interrupted workflow recovery
+- `test_split.py` — batch split behavior
+- `test_tasks_dir.py` — tasks directory handling
+- `test_auto_select.py` — auto-select logic
+- `test_lock_atomicity.py` — lock file atomicity
+- `test_workflow_persistence.py` — workflow state persistence
+- `test_inactivity_timeout.py` — inactivity timeout handling
+- `test_scenario_flows.py` — cross-cutting scenario flows
+
+The integration test suite is well-organized around features (checkpoint, choice, parallel, loop, extraction, etc.) rather than implementation phases. No restructuring was required.

fdsx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenfdev
+
+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.

fdsx-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+graft src
+include pyproject.toml
+include README.md
+include LICENSE
+
+prune .claude
+prune .takt
+prune .specify
+prune .worktree
+prune .fdsx
+prune specs
+
+exclude .gitignore
+exclude .worktreeinclude
+exclude docker-compose.yml
+exclude uv.lock
+
+global-exclude *.pyc
+global-exclude __pycache__

fdsx-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: fdsx
+Version: 0.1.0
+Summary: Declarative AI agent workflow execution framework
+Author: kenfdev
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kenfdev/fdsx
+Project-URL: Repository, https://github.com/kenfdev/fdsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: langgraph-checkpoint-sqlite<5,>=3
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: structlog>=24
+Requires-Dist: uuid-utils>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6; extra == "dev"
+Requires-Dist: pre-commit>=3; extra == "dev"
+Dynamic: license-file
+
+# fdsx — Flow-Driven Stateful eXecution
+
+[![PyPI version](https://img.shields.io/pypi/v/fdsx.svg)](https://pypi.org/project/fdsx/)
+
+A lightweight framework for building and executing complex AI agent workflows using declarative YAML definitions.
+
+## Overview
+
+fdsx enables you to define AI agent workflows in YAML, combining the durability of LangGraph (checkpoint, interrupt, conditional routing) with the declarative structure of AWS Step Functions.
+
+**Key features:**
+- Declarative YAML-based workflow definition
+- Stateful execution with checkpoint/resume
+- Parallel execution with branch aggregation
+- Batch task processing
+- Multiple LLM provider support (Claude, OpenCode, and more)
+
+## Installation
+
+```bash
+pip install fdsx
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install fdsx
+```
+
+## Quick Start
+
+Create a simple YAML workflow file:
+
+```yaml
+name: SimpleFlow
+start_at: greet
+version: "1.0"
+
+states:
+  greet:
+    type: task
+    provider: system
+    command: "echo 'Hello from fdsx!'"
+    result_path: $.message
+    end: true
+```
+
+Run it:
+
+```bash
+fdsx run simple_flow.yaml
+```
+
+## Feature Overview
+
+### State Types
+- **task** — Execute LLM or CLI commands
+- **parallel** — Run multiple branches concurrently
+- **choice** — Conditional routing based on variables
+- **wait** — Pause for human approval or webhook callback
+- **pass** — Pass-through state for data transformation
+
+### Parallel Execution
+Define parallel branches that execute simultaneously with aggregation strategies (majority vote, all, any).
+
+### Checkpoint & Resume
+Flows automatically persist state. Resume from interruption with:
+```bash
+fdsx resume --thread-id <thread_id>
+```
+
+### Batch Tasks
+Process multiple tasks in batch mode:
+```bash
+fdsx run workflow.yaml --tasks tasks.md
+```
+
+### Structured Logging
+All execution details are logged to `runs/<thread_id>.json`.
+
+### Provider Support
+Use any CLI-based LLM provider: Claude, Codex, OpenCode, or system commands.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `fdsx run <workflow.yaml>` | Execute a workflow |
+| `fdsx run <workflow.yaml> --input key=value` | Pass input variables |
+| `fdsx resume --thread-id <thread_id>` | Resume from checkpoint |
+| `fdsx validate <workflow.yaml>` | Validate YAML syntax |
+| `fdsx list` | List recent runs |
+
+## Example Workflow
+
+```yaml
+name: Plan-Implement-Review Loop
+start_at: plan
+version: "1.0"
+max_loop: 3
+
+states:
+  plan:
+    type: task
+    provider: claude
+    model: claude-sonnet-4-6
+    prompt_template: |
+      You are a planning agent. Break down the following task into clear,
+      actionable implementation steps.
+
+      Task: {task}
+    result_path: $.plan
+    next: implement
+
+  implement:
+    type: task
+    provider: opencode
+    model: opencode/minimax-m2.5-free
+    prompt_template: |
+      You are an implementation agent. Follow this plan exactly.
+
+      Plan: {plan}
+    result_path: $.implementation
+    next: review
+
+  review:
+    type: task
+    provider: codex
+    model: gpt-5.4
+    prompt_template: |
+      Review the implementation against the plan.
+
+      Plan: {plan}
+      Implementation: {implementation}
+    result_path: $.review
+    next: check_review
+
+  check_review:
+    type: choice
+    choices:
+      - variable: $.review
+        operator: contains
+        value: "APPROVED"
+        next: done
+    default: implement
+
+  done:
+    type: pass
+    end: true
+```
+
+Run this example:
+```bash
+fdsx run examples/workflows/plan-implement-review.yaml --input task="Build a web calculator"
+```
+
+## License
+
+MIT License.

fdsx-0.1.0/README.md

@@ -0,0 +1,159 @@
+# fdsx — Flow-Driven Stateful eXecution
+
+[![PyPI version](https://img.shields.io/pypi/v/fdsx.svg)](https://pypi.org/project/fdsx/)
+
+A lightweight framework for building and executing complex AI agent workflows using declarative YAML definitions.
+
+## Overview
+
+fdsx enables you to define AI agent workflows in YAML, combining the durability of LangGraph (checkpoint, interrupt, conditional routing) with the declarative structure of AWS Step Functions.
+
+**Key features:**
+- Declarative YAML-based workflow definition
+- Stateful execution with checkpoint/resume
+- Parallel execution with branch aggregation
+- Batch task processing
+- Multiple LLM provider support (Claude, OpenCode, and more)
+
+## Installation
+
+```bash
+pip install fdsx
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install fdsx
+```
+
+## Quick Start
+
+Create a simple YAML workflow file:
+
+```yaml
+name: SimpleFlow
+start_at: greet
+version: "1.0"
+
+states:
+  greet:
+    type: task
+    provider: system
+    command: "echo 'Hello from fdsx!'"
+    result_path: $.message
+    end: true
+```
+
+Run it:
+
+```bash
+fdsx run simple_flow.yaml
+```
+
+## Feature Overview
+
+### State Types
+- **task** — Execute LLM or CLI commands
+- **parallel** — Run multiple branches concurrently
+- **choice** — Conditional routing based on variables
+- **wait** — Pause for human approval or webhook callback
+- **pass** — Pass-through state for data transformation
+
+### Parallel Execution
+Define parallel branches that execute simultaneously with aggregation strategies (majority vote, all, any).
+
+### Checkpoint & Resume
+Flows automatically persist state. Resume from interruption with:
+```bash
+fdsx resume --thread-id <thread_id>
+```
+
+### Batch Tasks
+Process multiple tasks in batch mode:
+```bash
+fdsx run workflow.yaml --tasks tasks.md
+```
+
+### Structured Logging
+All execution details are logged to `runs/<thread_id>.json`.
+
+### Provider Support
+Use any CLI-based LLM provider: Claude, Codex, OpenCode, or system commands.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `fdsx run <workflow.yaml>` | Execute a workflow |
+| `fdsx run <workflow.yaml> --input key=value` | Pass input variables |
+| `fdsx resume --thread-id <thread_id>` | Resume from checkpoint |
+| `fdsx validate <workflow.yaml>` | Validate YAML syntax |
+| `fdsx list` | List recent runs |
+
+## Example Workflow
+
+```yaml
+name: Plan-Implement-Review Loop
+start_at: plan
+version: "1.0"
+max_loop: 3
+
+states:
+  plan:
+    type: task
+    provider: claude
+    model: claude-sonnet-4-6
+    prompt_template: |
+      You are a planning agent. Break down the following task into clear,
+      actionable implementation steps.
+
+      Task: {task}
+    result_path: $.plan
+    next: implement
+
+  implement:
+    type: task
+    provider: opencode
+    model: opencode/minimax-m2.5-free
+    prompt_template: |
+      You are an implementation agent. Follow this plan exactly.
+
+      Plan: {plan}
+    result_path: $.implementation
+    next: review
+
+  review:
+    type: task
+    provider: codex
+    model: gpt-5.4
+    prompt_template: |
+      Review the implementation against the plan.
+
+      Plan: {plan}
+      Implementation: {implementation}
+    result_path: $.review
+    next: check_review
+
+  check_review:
+    type: choice
+    choices:
+      - variable: $.review
+        operator: contains
+        value: "APPROVED"
+        next: done
+    default: implement
+
+  done:
+    type: pass
+    end: true
+```
+
+Run this example:
+```bash
+fdsx run examples/workflows/plan-implement-review.yaml --input task="Build a web calculator"
+```
+
+## License
+
+MIT License.