choola 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. choola-0.1.0/LICENSE +194 -0
  2. choola-0.1.0/MANIFEST.in +3 -0
  3. choola-0.1.0/PKG-INFO +184 -0
  4. choola-0.1.0/README.md +166 -0
  5. choola-0.1.0/choola/CLAUDE.md +91 -0
  6. choola-0.1.0/choola/__init__.py +15 -0
  7. choola-0.1.0/choola/__main__.py +18 -0
  8. choola-0.1.0/choola/cli.py +314 -0
  9. choola-0.1.0/choola/core/__init__.py +0 -0
  10. choola-0.1.0/choola/core/base_node.py +116 -0
  11. choola-0.1.0/choola/core/nodes/__init__.py +0 -0
  12. choola-0.1.0/choola/core/nodes/form_trigger.py +225 -0
  13. choola-0.1.0/choola/core/nodes/llm.py +181 -0
  14. choola-0.1.0/choola/core/nodes/webhook_trigger.py +64 -0
  15. choola-0.1.0/choola/database.py +200 -0
  16. choola-0.1.0/choola/server.py +1192 -0
  17. choola-0.1.0/choola/static/assets/index-DdVKsHd4.css +1 -0
  18. choola-0.1.0/choola/static/assets/index-ovm_A6rW.js +22 -0
  19. choola-0.1.0/choola/static/dist/assets/index-Cosi1UXQ.js +22 -0
  20. choola-0.1.0/choola/static/dist/assets/index-DdVKsHd4.css +1 -0
  21. choola-0.1.0/choola/static/dist/favicon.svg +1 -0
  22. choola-0.1.0/choola/static/dist/icons.svg +24 -0
  23. choola-0.1.0/choola/static/dist/index.html +14 -0
  24. choola-0.1.0/choola/static/favicon.svg +1 -0
  25. choola-0.1.0/choola/static/icons.svg +24 -0
  26. choola-0.1.0/choola/static/index.html +14 -0
  27. choola-0.1.0/choola.egg-info/PKG-INFO +184 -0
  28. choola-0.1.0/choola.egg-info/SOURCES.txt +32 -0
  29. choola-0.1.0/choola.egg-info/dependency_links.txt +1 -0
  30. choola-0.1.0/choola.egg-info/entry_points.txt +2 -0
  31. choola-0.1.0/choola.egg-info/requires.txt +8 -0
  32. choola-0.1.0/choola.egg-info/top_level.txt +1 -0
  33. choola-0.1.0/pyproject.toml +34 -0
  34. choola-0.1.0/setup.cfg +4 -0
choola-0.1.0/LICENSE ADDED
@@ -0,0 +1,194 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship made available under
36
+ the License, as indicated by a copyright notice that is included in
37
+ or attached to the work (an example is provided in the Appendix below).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other transformations
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean, as submitted to the Licensor for inclusion
48
+ in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes
50
+ of this definition, "submitted" means any form of electronic, verbal,
51
+ or written communication sent to the Licensor or its representatives,
52
+ including but not limited to communication on electronic mailing lists,
53
+ source code control systems, and issue tracking systems that are managed
54
+ by, or on behalf of, the Licensor for the purpose of discussing and
55
+ improving the Work, but excluding communication that is conspicuously
56
+ marked or designated in writing by the copyright owner as "Not a
57
+ Contribution."
58
+
59
+ "Contributor" shall mean Licensor and any Legal Entity on behalf of
60
+ whom a Contribution has been received by the Licensor and included
61
+ within the Work.
62
+
63
+ 2. Grant of Copyright License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ copyright license to reproduce, prepare Derivative Works of,
67
+ publicly display, publicly perform, sublicense, and distribute the
68
+ Work and such Derivative Works in Source or Object form.
69
+
70
+ 3. Grant of Patent License. Subject to the terms and conditions of
71
+ this License, each Contributor hereby grants to You a perpetual,
72
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
73
+ (except as stated in this section) patent license to make, have made,
74
+ use, offer to sell, sell, import, and otherwise transfer the Work,
75
+ where such license applies only to those patent claims licensable
76
+ by such Contributor that are necessarily infringed by their
77
+ Contribution(s) alone or by the combination of their Contribution(s)
78
+ with the Work to which such Contribution(s) was submitted. If You
79
+ institute patent litigation against any entity (including a cross-claim
80
+ or counterclaim in a lawsuit) alleging that the Work or any other
81
+ Contribution incorporated within the Work constitutes patent or
82
+ contributory patent infringement, then any patent licenses granted to
83
+ You under this License for that Work shall terminate as of the date
84
+ such litigation is filed.
85
+
86
+ 4. Redistribution. You may reproduce and distribute copies of the
87
+ Work or Derivative Works thereof in any medium, with or without
88
+ modifications, and in Source or Object form, provided that You
89
+ meet the following conditions:
90
+
91
+ (a) You must give any other recipients of the Work or Derivative
92
+ Works a copy of this License; and
93
+
94
+ (b) You must cause any modified files to carry prominent notices
95
+ stating that You changed the files; and
96
+
97
+ (c) You must retain, in the Source form of any Derivative Works
98
+ that You distribute, all copyright, patent, trademark, and
99
+ attribution notices from the Source form of the Work,
100
+ excluding those notices that do not pertain to any part of
101
+ the Derivative Works; and
102
+
103
+ (d) If the Work includes a "NOTICE" text file as part of its
104
+ distribution, You must include a readable copy of the
105
+ attribution notices contained within such NOTICE file, in
106
+ at least one of the following places: within a NOTICE text
107
+ file distributed as part of the Derivative Works; within
108
+ the Source form or documentation, if provided along with the
109
+ Derivative Works; or, within a display generated by the
110
+ Derivative Works, if and wherever such third-party notices
111
+ normally appear. The contents of the NOTICE file are for
112
+ informational purposes only and do not modify the License.
113
+ You may add Your own attribution notices within Derivative
114
+ Works that You distribute, alongside or in addition to the
115
+ NOTICE text from the Work, provided that such additional
116
+ attribution notices cannot be construed as modifying the
117
+ License.
118
+
119
+ You may add Your own license statement for Your modifications and
120
+ may provide additional grant of rights to use, copy, modify, merge,
121
+ publish, distribute, sublicense, and/or sell copies of the
122
+ Contribution, either on an exclusive basis, consistent with the
123
+ terms of this License.
124
+
125
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
126
+ any Contribution intentionally submitted for inclusion in the Work
127
+ by You to the Licensor shall be under the terms and conditions of
128
+ this License, without any additional terms or conditions.
129
+ Notwithstanding the above, nothing herein shall supersede or modify
130
+ the terms of any separate license agreement you may have executed
131
+ with Licensor regarding such Contributions.
132
+
133
+ 6. Trademarks. This License does not grant permission to use the trade
134
+ names, trademarks, service marks, or product names of the Licensor,
135
+ except as required for reasonable and customary use in describing the
136
+ origin of the Work and reproducing the content of the NOTICE file.
137
+
138
+ 7. Disclaimer of Warranty. Unless required by applicable law or
139
+ agreed to in writing, Licensor provides the Work (and each
140
+ Contributor provides its Contributions) on an "AS IS" BASIS,
141
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
142
+ implied, including, without limitation, any warranties or conditions
143
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
144
+ PARTICULAR PURPOSE. You are solely responsible for determining the
145
+ appropriateness of using or reproducing the Work and assume any
146
+ risks associated with Your exercise of permissions under this License.
147
+
148
+ 8. Limitation of Liability. In no event and under no legal theory,
149
+ whether in tort (including negligence), contract, or otherwise,
150
+ unless required by applicable law (such as deliberate and grossly
151
+ negligent acts) or agreed to in writing, shall any Contributor be
152
+ liable to You for damages, including any direct, indirect, special,
153
+ incidental, or exemplary damages of any character arising as a
154
+ result of this License or out of the use or inability to use the
155
+ Work (including but not limited to damages for loss of goodwill,
156
+ work stoppage, computer failure or malfunction, or all other
157
+ commercial damages or losses), even if such Contributor has been
158
+ advised of the possibility of such damages.
159
+
160
+ 9. Accepting Warranty or Additional Liability. While redistributing
161
+ the Work or Derivative Works thereof, You may offer, and charge a
162
+ fee for, acceptance of support, warranty, indemnity, or other
163
+ liability obligations and/or rights consistent with this License.
164
+ However, in accepting such obligations, You may offer such obligations
165
+ only on Your own behalf and on Your sole responsibility, not on behalf
166
+ of any other Contributor, and only if You agree to indemnify,
167
+ defend, and hold each Contributor harmless for any liability
168
+ incurred by, or claims asserted against, such Contributor by reason
169
+ of your accepting any such warranty or additional liability.
170
+
171
+ END OF TERMS AND CONDITIONS
172
+
173
+ APPENDIX: How to apply the Apache License to your work.
174
+
175
+ To apply the Apache License to your work, attach the following
176
+ boilerplate notice, with the fields enclosed by brackets "[]"
177
+ replaced with your own identifying information. (Don't include
178
+ the brackets!) The text should be enclosed in the appropriate
179
+ comment syntax for the file format in use. In brief, the copyright
180
+ notice for each file should state:
181
+
182
+ Copyright [yyyy] [name of copyright owner]
183
+
184
+ Licensed under the Apache License, Version 2.0 (the "License");
185
+ you may not use this file except in compliance with the License.
186
+ You may obtain a copy of the License at
187
+
188
+ http://www.apache.org/licenses/LICENSE-2.0
189
+
190
+ Unless required by applicable law or agreed to in writing, software
191
+ distributed under the License is distributed on an "AS IS" BASIS,
192
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
193
+ See the License for the specific language governing permissions and
194
+ limitations under the License.
@@ -0,0 +1,3 @@
1
+ recursive-include choola/static *
2
+ include choola/CLAUDE.md
3
+ include README.md
choola-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,184 @@
1
+ Metadata-Version: 2.4
2
+ Name: choola
3
+ Version: 0.1.0
4
+ Summary: A workflow engine for VS Code developers — build, run, and automate workflows with Python nodes.
5
+ License-Expression: Apache-2.0
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: anthropic>=0.49.0
10
+ Requires-Dist: click>=8.1
11
+ Requires-Dist: flask>=3.0
12
+ Requires-Dist: google-genai>=1.0.0
13
+ Requires-Dist: requests>=2.31.0
14
+ Requires-Dist: aiofiles>=23.0
15
+ Requires-Dist: google-api-python-client>=2.0
16
+ Requires-Dist: google-auth>=2.0
17
+ Dynamic: license-file
18
+
19
+ # Choola
20
+
21
+ A workflow automation engine where you build multi-step pipelines from self-contained Python nodes. Includes a visual editor (React + React Flow), a Flask API, and a CLI runner.
22
+
23
+ ## Prerequisites
24
+
25
+ - Python 3.12+
26
+ - Node.js 18+ and npm
27
+
28
+ ## Setup
29
+
30
+ ```bash
31
+ # Clone the repo
32
+ git clone <repo-url>
33
+ cd choola
34
+
35
+ # Create a Python virtual environment and install dependencies
36
+ python3 -m venv venv
37
+ source venv/bin/activate
38
+ pip install -r requirements.txt
39
+
40
+ # Build the frontend
41
+ cd frontend
42
+ npm install
43
+ npm run build
44
+ cd ..
45
+ ```
46
+
47
+ ## Running
48
+
49
+ ### Web UI + API
50
+
51
+ ```bash
52
+ python server.py
53
+ ```
54
+
55
+ Opens at [http://localhost:5000](http://localhost:5000). The visual editor lets you create workflows, add nodes, wire them together, and run them with live status streaming (SSE).
56
+
57
+ ### CLI
58
+
59
+ ```bash
60
+ # List available workflows
61
+ python cli.py list
62
+
63
+ # Run a workflow with a JSON payload
64
+ python cli.py run <workflow_name> --payload '{"key": "value"}'
65
+
66
+ # Create a new empty workflow
67
+ python cli.py create <workflow_name>
68
+
69
+ # List nodes in a workflow
70
+ python cli.py nodes <workflow_name>
71
+ ```
72
+
73
+ ## Project Structure
74
+
75
+ ```
76
+ choola/
77
+ ├── server.py # Flask API + serves the React frontend
78
+ ├── cli.py # Headless CLI runner
79
+ ├── database.py # SQLite store (globals + run logs)
80
+ ├── requirements.txt
81
+ ├── core/
82
+ │ └── base_node.py # Abstract base class for all nodes
83
+ ├── frontend/ # React + React Flow visual editor (Vite)
84
+ └── workflows/
85
+ └── <workflow_name>/
86
+ ├── topology.json # DAG definition (nodes + edges)
87
+ └── nodes/
88
+ ├── __init__.py
89
+ └── <node>.py # One file per node
90
+ ```
91
+
92
+ ## How Workflows Work
93
+
94
+ A workflow is a folder under `workflows/` containing:
95
+
96
+ - **`topology.json`** — defines the DAG: which nodes exist and how they connect.
97
+ - **`nodes/*.py`** — one Python file per node. Each node is a self-contained class that inherits from `BaseNode`, receives a JSON payload, does one thing, and returns the (possibly modified) payload to the next node.
98
+
99
+ The engine topologically sorts the nodes and executes them in order, passing the payload through the chain.
100
+
101
+ ## Writing a Node
102
+
103
+ Every node is a single `.py` file in `workflows/<name>/nodes/`. Here's the template:
104
+
105
+ ```python
106
+ """
107
+ @choola-node: MyNodeName
108
+ @category: processing
109
+ @description: Does one specific thing to the payload.
110
+ @input-payload:
111
+ - some_key (str): What this node expects
112
+ @output-payload:
113
+ - some_key (str): Same or transformed
114
+ - new_key (int): Something this node adds
115
+ @config-fields:
116
+ - threshold (int, default=10): Controls the threshold
117
+ @example-input: {"some_key": "hello"}
118
+ @example-output: {"some_key": "hello", "new_key": 42}
119
+ @side-effects: none
120
+ @errors: Raises ValueError if some_key is missing
121
+ """
122
+
123
+ from typing import Any
124
+
125
+ from core.base_node import BaseNode
126
+
127
+
128
+ class MyNodeName(BaseNode):
129
+ name = "My Node Name"
130
+ category = "processing"
131
+ description = "Does one specific thing to the payload."
132
+ fields = [
133
+ {"name": "threshold", "type": "number", "default": 10},
134
+ ]
135
+
136
+ async def execute(self, payload: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
137
+ # Your logic here
138
+ return payload
139
+ ```
140
+
141
+ ### Node rules
142
+
143
+ - **Self-contained** — all logic in one file, no cross-node imports.
144
+ - **JSON in, JSON out** — communicate only through the `payload` dict.
145
+ - **Docstring required** — the `@choola-node` markers make nodes discoverable by grep.
146
+
147
+ ### Categories
148
+
149
+ | Category | Use for |
150
+ |---|---|
151
+ | `input` | Data ingestion, entry points |
152
+ | `processing` | Transformation, enrichment |
153
+ | `routing` | Conditional branching |
154
+ | `output` | Sending results, notifications |
155
+ | `validation` | Data checks, guards |
156
+ | `integration` | External API calls |
157
+
158
+ ### Global variables
159
+
160
+ Nodes can persist data across runs using SQLite-backed helpers:
161
+
162
+ ```python
163
+ value = await self.get_global("my_key")
164
+ await self.set_global("my_key", "new_value")
165
+ ```
166
+
167
+ ## API Endpoints
168
+
169
+ | Method | Path | Description |
170
+ |---|---|---|
171
+ | GET | `/api/nodes` | List all registered node types |
172
+ | GET | `/api/workflows` | List all workflows |
173
+ | POST | `/api/workflows` | Create a new workflow |
174
+ | GET | `/api/workflows/<name>/topology` | Get workflow topology |
175
+ | PUT | `/api/workflows/<name>/topology` | Update workflow topology |
176
+ | POST | `/api/workflows/<name>/run` | Execute a workflow |
177
+ | GET | `/api/workflows/<name>/stream/<run_id>` | SSE stream for live run status |
178
+
179
+ ## Using with Claude Code
180
+
181
+ This project includes slash commands for building workflows with AI assistance:
182
+
183
+ - **`/choola`** — describe what you want and Claude builds the full workflow (nodes + topology).
184
+ - **`/node`** — add a single node to an existing workflow.
choola-0.1.0/README.md ADDED
@@ -0,0 +1,166 @@
1
+ # Choola
2
+
3
+ A workflow automation engine where you build multi-step pipelines from self-contained Python nodes. Includes a visual editor (React + React Flow), a Flask API, and a CLI runner.
4
+
5
+ ## Prerequisites
6
+
7
+ - Python 3.12+
8
+ - Node.js 18+ and npm
9
+
10
+ ## Setup
11
+
12
+ ```bash
13
+ # Clone the repo
14
+ git clone <repo-url>
15
+ cd choola
16
+
17
+ # Create a Python virtual environment and install dependencies
18
+ python3 -m venv venv
19
+ source venv/bin/activate
20
+ pip install -r requirements.txt
21
+
22
+ # Build the frontend
23
+ cd frontend
24
+ npm install
25
+ npm run build
26
+ cd ..
27
+ ```
28
+
29
+ ## Running
30
+
31
+ ### Web UI + API
32
+
33
+ ```bash
34
+ python server.py
35
+ ```
36
+
37
+ Opens at [http://localhost:5000](http://localhost:5000). The visual editor lets you create workflows, add nodes, wire them together, and run them with live status streaming (SSE).
38
+
39
+ ### CLI
40
+
41
+ ```bash
42
+ # List available workflows
43
+ python cli.py list
44
+
45
+ # Run a workflow with a JSON payload
46
+ python cli.py run <workflow_name> --payload '{"key": "value"}'
47
+
48
+ # Create a new empty workflow
49
+ python cli.py create <workflow_name>
50
+
51
+ # List nodes in a workflow
52
+ python cli.py nodes <workflow_name>
53
+ ```
54
+
55
+ ## Project Structure
56
+
57
+ ```
58
+ choola/
59
+ ├── server.py # Flask API + serves the React frontend
60
+ ├── cli.py # Headless CLI runner
61
+ ├── database.py # SQLite store (globals + run logs)
62
+ ├── requirements.txt
63
+ ├── core/
64
+ │ └── base_node.py # Abstract base class for all nodes
65
+ ├── frontend/ # React + React Flow visual editor (Vite)
66
+ └── workflows/
67
+ └── <workflow_name>/
68
+ ├── topology.json # DAG definition (nodes + edges)
69
+ └── nodes/
70
+ ├── __init__.py
71
+ └── <node>.py # One file per node
72
+ ```
73
+
74
+ ## How Workflows Work
75
+
76
+ A workflow is a folder under `workflows/` containing:
77
+
78
+ - **`topology.json`** — defines the DAG: which nodes exist and how they connect.
79
+ - **`nodes/*.py`** — one Python file per node. Each node is a self-contained class that inherits from `BaseNode`, receives a JSON payload, does one thing, and returns the (possibly modified) payload to the next node.
80
+
81
+ The engine topologically sorts the nodes and executes them in order, passing the payload through the chain.
82
+
83
+ ## Writing a Node
84
+
85
+ Every node is a single `.py` file in `workflows/<name>/nodes/`. Here's the template:
86
+
87
+ ```python
88
+ """
89
+ @choola-node: MyNodeName
90
+ @category: processing
91
+ @description: Does one specific thing to the payload.
92
+ @input-payload:
93
+ - some_key (str): What this node expects
94
+ @output-payload:
95
+ - some_key (str): Same or transformed
96
+ - new_key (int): Something this node adds
97
+ @config-fields:
98
+ - threshold (int, default=10): Controls the threshold
99
+ @example-input: {"some_key": "hello"}
100
+ @example-output: {"some_key": "hello", "new_key": 42}
101
+ @side-effects: none
102
+ @errors: Raises ValueError if some_key is missing
103
+ """
104
+
105
+ from typing import Any
106
+
107
+ from core.base_node import BaseNode
108
+
109
+
110
+ class MyNodeName(BaseNode):
111
+ name = "My Node Name"
112
+ category = "processing"
113
+ description = "Does one specific thing to the payload."
114
+ fields = [
115
+ {"name": "threshold", "type": "number", "default": 10},
116
+ ]
117
+
118
+ async def execute(self, payload: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
119
+ # Your logic here
120
+ return payload
121
+ ```
122
+
123
+ ### Node rules
124
+
125
+ - **Self-contained** — all logic in one file, no cross-node imports.
126
+ - **JSON in, JSON out** — communicate only through the `payload` dict.
127
+ - **Docstring required** — the `@choola-node` markers make nodes discoverable by grep.
128
+
129
+ ### Categories
130
+
131
+ | Category | Use for |
132
+ |---|---|
133
+ | `input` | Data ingestion, entry points |
134
+ | `processing` | Transformation, enrichment |
135
+ | `routing` | Conditional branching |
136
+ | `output` | Sending results, notifications |
137
+ | `validation` | Data checks, guards |
138
+ | `integration` | External API calls |
139
+
140
+ ### Global variables
141
+
142
+ Nodes can persist data across runs using SQLite-backed helpers:
143
+
144
+ ```python
145
+ value = await self.get_global("my_key")
146
+ await self.set_global("my_key", "new_value")
147
+ ```
148
+
149
+ ## API Endpoints
150
+
151
+ | Method | Path | Description |
152
+ |---|---|---|
153
+ | GET | `/api/nodes` | List all registered node types |
154
+ | GET | `/api/workflows` | List all workflows |
155
+ | POST | `/api/workflows` | Create a new workflow |
156
+ | GET | `/api/workflows/<name>/topology` | Get workflow topology |
157
+ | PUT | `/api/workflows/<name>/topology` | Update workflow topology |
158
+ | POST | `/api/workflows/<name>/run` | Execute a workflow |
159
+ | GET | `/api/workflows/<name>/stream/<run_id>` | SSE stream for live run status |
160
+
161
+ ## Using with Claude Code
162
+
163
+ This project includes slash commands for building workflows with AI assistance:
164
+
165
+ - **`/choola`** — describe what you want and Claude builds the full workflow (nodes + topology).
166
+ - **`/node`** — add a single node to an existing workflow.
@@ -0,0 +1,91 @@
1
+ # Choola — Workflow Engine
2
+
3
+ ## Project Structure
4
+
5
+ ```
6
+ workflows/<name>/
7
+ topology.json # DAG: nodes + edges
8
+ nodes/
9
+ __init__.py
10
+ <node_name>.py # One file per node, self-contained
11
+ choola.db # SQLite store (auto-created on first run)
12
+ ```
13
+
14
+ The `choola` package is installed separately via pip. Core infrastructure lives there.
15
+
16
+ ## Node Contract
17
+
18
+ Every node file MUST:
19
+
20
+ 1. Start with the `@choola-node` grep-friendly docstring (see any file in `workflows/*/nodes/`)
21
+ 2. Inherit from `choola.core.base_node.BaseNode`
22
+ 3. Be self-contained — no cross-node imports
23
+ 4. Communicate exclusively via `payload: dict` passed through `execute()`
24
+ 5. Declare `name`, `category`, `description`, and `fields` class attributes
25
+
26
+ ## Core Nodes
27
+
28
+ These live inside the `choola` package and are available to all workflows.
29
+
30
+ **Rule:** Core nodes must NEVER be instantiated directly in a workflow. Instead, create a new class inside the workflow's `nodes/` directory that extends the core node. This wrapper class is what gets referenced in `topology.json`.
31
+
32
+ ### WebhookTrigger (`core.nodes.webhook_trigger.WebhookTrigger`)
33
+ - **Category:** input
34
+ - **Purpose:** Starts a workflow when an HTTP request hits a registered endpoint.
35
+ - **Config fields:**
36
+ - `path` (str, required) — URL path, e.g. `/hooks/my-endpoint`
37
+ - `method` (select: GET/POST/PUT/DELETE, default `POST`)
38
+ - `response_mode` (select: `immediate` returns 202 right away, `after_workflow` waits for result)
39
+ - **Output payload:** `{ method, headers, query, body }`
40
+
41
+ ### FormTrigger (`core.nodes.form_trigger.FormTrigger`)
42
+ - **Category:** input
43
+ - **Purpose:** Serves an HTML form at a URL path; form submission triggers the workflow.
44
+ - **Config fields:**
45
+ - `path` (str, required) — URL path, e.g. `/forms/contact`
46
+ - `form_title` (str) — heading above the form
47
+ - `form_description` (str) — description text below the title
48
+ - `form_fields` (json) — array of field definitions, each with:
49
+ - `label`, `field_name`, `field_type` (text/email/number/password/textarea/dropdown/date/checkbox)
50
+ - `required` (bool), `placeholder` (str), `options` (list, dropdown only), `default_value` (str)
51
+ - `response_mode` (select: `after_workflow` returns JSON, `redirect` shows thank-you page)
52
+ - `submit_label` (str, default `Submit`)
53
+ - **Output payload:** `{ form_data: {field_name: value, ...}, submitted_at: "<ISO timestamp>" }`
54
+
55
+ ### LLM (`core.nodes.llm.LLM`)
56
+ - **Category:** processing
57
+ - **Purpose:** Sends a prompt to an LLM (Claude or Gemini) and returns the response.
58
+ - **Requires:** A stored credential (managed via Settings > Credentials or `POST /api/credentials`)
59
+ - **Config fields:**
60
+ - `credential_name` (str, required) — name of the stored credential to use
61
+ - `provider` (select: `claude`, `gemini`) — which LLM provider
62
+ - `model` (str) — model ID; defaults to `claude-sonnet-4-20250514` / `gemini-2.0-flash`
63
+ - `prompt` (textarea, required) — prompt template; use `{key}` to interpolate payload values
64
+ - `system_prompt` (textarea) — optional system prompt
65
+ - `max_tokens` (number, default 1024)
66
+ - `temperature` (number, default 1.0)
67
+ - **Output payload:** adds `llm_response`, `llm_model`, `llm_provider` to existing payload
68
+
69
+ ## Credentials
70
+
71
+ Credentials are stored in the SQLite database (`credentials` table) and accessed by nodes at runtime via `self.get_credential(name)`.
72
+
73
+ ### API
74
+ - `GET /api/credentials` — list all credentials (values masked)
75
+ - `POST /api/credentials` — create/update: `{ name, provider, value }`
76
+ - `DELETE /api/credentials/<name>` — delete a credential
77
+
78
+ ### Node access
79
+ Any node can call `await self.get_credential("my-key")` to retrieve a credential dict with keys: `name`, `provider`, `value`, `created_at`, `updated_at`.
80
+
81
+ ## CLI
82
+
83
+ ```bash
84
+ choola init # Set up a new project (run once)
85
+ choola start # Start the server at http://localhost:5000
86
+ choola start --host 0.0.0.0 --port 8080 # Bind to all interfaces
87
+ choola create <workflow_name> # Scaffold a new workflow
88
+ choola list # List all workflows
89
+ choola run <workflow_name> --payload '{"key": "value"}' # Run headlessly
90
+ choola nodes # List core node types
91
+ ```
@@ -0,0 +1,15 @@
1
+ # Copyright 2026 Ivan Grosny
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ __version__ = "0.1.0"
@@ -0,0 +1,18 @@
1
+ # Copyright 2026 Ivan Grosny
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ from choola.cli import main
16
+
17
+ if __name__ == "__main__":
18
+ main()