twpm 0.2.3__tar.gz

twpm-0.2.3/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv sync:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

twpm-0.2.3/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

twpm-0.2.3/.python-version

@@ -0,0 +1 @@
+3.12.12

twpm-0.2.3/CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+twpm is a workflow builder library that simplifies creating dynamic workflows using a linked-list-based execution model. The project combines data structure implementations (for learning) with a workflow orchestration system.
+
+## Common Development Commands
+
+This project uses **uv** for Python package management. uv is a fast Python package installer and resolver written in Rust.
+
+### Setup
+```bash
+# Install dependencies (including dev dependencies)
+uv sync
+
+# Install only production dependencies
+uv sync --no-dev
+```
+
+### Testing
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/core/test_orchestrator.py
+
+# Run single test
+uv run pytest tests/core/test_orchestrator.py::TestOrchestrator::test_single_node_execution
+```
+
+### Linting and Formatting
+```bash
+# Check code with ruff (linter)
+uv run ruff check .
+
+# Auto-fix linting issues
+uv run ruff check --fix .
+
+# Format code with ruff
+uv run ruff format .
+
+# Check formatting without changes
+uv run ruff format --check .
+```
+
+### Building
+```bash
+# Build package for distribution
+uv build
+
+# Build wheel only
+uv build --wheel
+```
+
+## Architecture
+
+### Core Workflow System (`twpm/core/`)
+
+The workflow system is built on a linked-list architecture where nodes execute sequentially:
+
+1. **Node** (`core/base/node.py`): Abstract base class for all workflow nodes
+   - Nodes form a singly-linked list via `next` and `previous` references
+   - Each node implements `async execute(data: ListData) -> NodeResult`
+   - Node execution is wrapped with `@safe_execute()` decorator to guarantee NodeResult return
+
+2. **Orchestrator** (`core/orchestrator.py`): Main workflow execution engine
+   - Manages node execution flow sequentially
+   - Maintains shared `ListData` for passing information between nodes
+   - Handles node states: `DEFAULT`, `COMPLETE`, `FAILED`, `AWAITING_INPUT`
+   - Key methods:
+     - `start(start_node)`: Initialize workflow with starting node
+     - `process(input=None)`: Execute nodes until completion or input needed
+     - `reset()`: Return to beginning of workflow
+
+3. **Node Types** (`core/primitives/`):
+   - **TaskNode**: Executes async functions that return bool for success/failure
+   - **ConditionalNode**: Branching logic that dynamically inserts next node based on condition
+     - Uses `Cursor.insert()` to modify the linked list at runtime
+     - Must call `set_condition(condition_func, true_node, false_node)` before execution
+
+4. **Data Flow** (`core/base/models.py`):
+   - **ListData**: Dictionary-like container passed between nodes
+     - Provides `get()`, `update()`, `has()`, and bracket notation access
+   - **NodeResult**: Return value from node execution
+     - `success`: bool indicating execution success
+     - `data`: dict merged into shared ListData
+     - `is_awaiting_input`: pauses workflow for external input
+     - `message`: contextual information
+
+5. **Cursor** (`core/cursor.py`): Utility for linked-list manipulation
+   - `Cursor.insert(target, new_node)`: Inserts new_node after target
+   - Used by ConditionalNode to dynamically modify workflow structure
+
+### Data Structures (`twpm/dsa/`)
+
+Contains learning implementations:
+- `linkedlist.py`: Singly-linked list implementation
+- `doublelinkedlist.py`: Doubly-linked list implementation
+
+### Testing Pattern
+
+Tests use mock nodes with configurable behavior:
+- `MockNode`: Configurable success/failure, data output, awaiting_input state
+- `FailingNode`: Raises exceptions to test error handling
+- `QuestionNode`: Demonstrates input-awaiting pattern with validation
+
+All tests are async using `@pytest.mark.asyncio`.
+
+## Important Implementation Details
+
+### Safe Execution Decorator
+All node `execute()` methods must be decorated with `@safe_execute()`. This decorator:
+- Catches exceptions and converts them to failed NodeResult
+- Prevents exceptions from propagating to orchestrator
+- Logs errors with node identifier
+
+### Workflow Pause/Resume Pattern
+Nodes can pause workflow execution by returning `NodeResult(is_awaiting_input=True)`:
+1. First `process()` call: node returns `is_awaiting_input=True`, status becomes `AWAITING_INPUT`
+2. Orchestrator stops, current node remains set
+3. Second `process(input="...")` call: orchestrator provides input via `ListData["_user_input"]`
+4. Node processes input and returns regular result to continue workflow
+
+### Dynamic Workflow Modification
+ConditionalNode demonstrates runtime workflow structure changes:
+- Evaluates condition function
+- Uses `Cursor.insert()` to inject appropriate branch into linked list
+- Allows for dynamic, data-driven workflow paths
+
+### Node Status Lifecycle
+- `DEFAULT`: Ready to execute (reset before each execution)
+- `COMPLETE`: Successfully executed
+- `FAILED`: Execution failed (stops workflow)
+- `AWAITING_INPUT`: Paused waiting for input (workflow can resume)

twpm-0.2.3/LICENSE

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

twpm-0.2.3/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: twpm
+Version: 0.2.3
+Summary: A simple workflow builder that takes the complexity out of building dynamic workflows
+Project-URL: Homepage, https://github.com/jacksonvieiracs/twpm
+Project-URL: Repository, https://github.com/jacksonvieiracs/twpm
+Project-URL: Issues, https://github.com/jacksonvieiracs/twpm/issues
+Author-email: Jackson Vieira <dev.jacksonvieira@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: async,n8n as code,orchestrator,task-orchestration,workflow,workflow-engine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Twpm
+
+A simple workflow builder that takes the complexity out of building dynamic workflows.
+
+## Motivation
+
+Twpm (twelve pm) is a simple workflow engine inspired by n8n, but now using all the benefits that Python offers. Build workflows where you control everything, and they can grow organically.
+
+The project was born from building several WhatsApp automation workflows. Each solution was unique, highly coupled, and had significant code duplication. Twpm solves this by providing a framework to create workflows that are fast to build, scalable, and highly decoupled.
+
+## Quick Start
+
+Get started with Twpm in just a few lines of code:
+
+```python
+import asyncio
+from twpm.core import Chain, Orchestrator
+from twpm.core.container import Container, ServiceScope
+from twpm.core.primitives import DisplayMessageNode, QuestionNode, SummaryNode
+from twpm.core.depedencies import Output
+
+workflow = (
+    Chain()
+    .add(DisplayMessageNode("Welcome!", key="welcome"))
+    .add(QuestionNode("What's your name?", key="name"))
+    .add(QuestionNode("What's your email?", key="email"))
+    .add(SummaryNode(
+        title="Thank you!",
+        fields=[("Name", "name"), ("Email", "email")],
+        key="summary"
+    ))
+    .build()
+)
+
+class ConsoleOutput:
+    async def send_text(self, text: str):
+        print(text, end=" ")
+
+async def main():
+    container = Container()
+    container.registry(Output, lambda: ConsoleOutput(), ServiceScope.SINGLETON)
+    orchestrator = Orchestrator(container)
+    
+    orchestrator.start(workflow)
+    await orchestrator.process()
+
+asyncio.run(main())
+```
+
+That's it! Twpm handles the rest!
+
+## Installation
+
+### Using uv
+
+```sh
+uv add twpm
+```
+
+### Using pip
+
+```sh
+pip install twpm
+```
+
+## Features
+
+- **Simple API**: Build workflows using an intuitive builder pattern or simple function calls
+- **Async Support**: Built on Python's asyncio for efficient async workflows
+- **Dependency Injection**: Lightweight IoC container for clean dependency management
+- **Built-in Primitives**: Ready-to-use nodes for common patterns:
+  - `DisplayMessageNode`: Display messages to users
+  - `QuestionNode`: Prompt for user input
+  - `PoolNode`: Multiple choice questions
+  - `QuizNode`: Quiz questions with correct answers
+  - `ConditionalNode`: Dynamic branching based on conditions
+  - `ProgressNode`: Show progress through workflow steps
+  - `SummaryNode`: Display collected data summaries
+  - `TaskNode`: Execute custom async tasks
+- **Type Safety**: Full type hints for better IDE support and error detection
+- **Extensible**: Easy to create custom nodes for your specific needs
+
+## Examples
+
+Check out the [examples directory](examples/):
+
+- **CLI Example** (`examples/cli/main.py`): A complete interactive CLI workflow demonstrating:
+  - User input collection
+  - Progress tracking
+  - Data summarization
+  - Quiz workflow with conditional routing based on results
+
+Run the example:
+
+```sh
+git clone https://github.com/jacksonvieiracs/twpm
+cd twpm
+```
+
+```sh
+uv run python3 examples/cli/main.py
+```
+
+Try the quiz workflow:
+
+```sh
+uv run python3 examples/cli/main.py --quiz
+```
+
+## Architecture
+
+### Fundamentals
+
+![Base](docs/linked-list.png)
+
+Approximately 40% of the codebase is a doubly-linked list implementation. Why use a linked list specifically? It guarantees a level of decoupling between components. Each node can define how the next node is processed, with the orchestrator intervening only when necessary. A node a stateful unit that stores state and contains the full logic. The magic happens when combining linked list fundamentals with an orchestrator that manages routing logic to advance, stop, or await.
+
+![Conditional example](docs/conditional-example.png)
+
+This example demonstrates the benefits of using a linked list data structure for controlling flow behavior. You can create a "condition node" that acts as a router to the next node in your flow based on a computed dynamic condition for example, based on the previous node's result.
+
+### Components
+
+![Base components](docs/core-components.png)
+
+#### Node
+
+A Node is a stateful unit of execution. Each node can define guards, execute custom logic, and dynamically choose the next node. Nodes form a double-linked structure (`prev`/`next`) enabling flexible routing based on runtime conditions.
+
+#### Chain
+
+A Chain is a double-linked list of nodes. It simplifies constructing pipelines by automatically connecting nodes and providing structural operations.
+
+#### Orchestrator
+
+The Orchestrator coordinates node execution. It decides which node should run next and whether to continue, await input, or stop, based on node results.
+
+#### Cursor
+
+The Cursor performs operations on the chain knowing only the "current node." It safely manages list mutations (insertion, replacement, deletion) without breaking the chain.
+
+#### Container
+
+The Container is a lightweight IoC system for injecting dependencies into nodes. It registers services, resolves them when needed, and manages lifecycles, without adding business logic.
+
+## License
+
+MIT