Add support for workflows

.github/workflows/pr-review-codex.yml

@@ -0,0 +1,67 @@
+name: Perform a code review when a pull request is created.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, labeled]
+
+jobs:
+  codex:
+    runs-on: ubuntu-24.04
+
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+
+    outputs:
+      final_message: ${{ steps.run_codex.outputs.final-message }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: refs/pull/${{ github.event.pull_request.number }}/merge
+
+      - name: Pre-fetch base and head refs for the PR
+        run: |
+          git fetch --no-tags origin \
+            ${{ github.event.pull_request.base.ref }} \
+            +refs/pull/${{ github.event.pull_request.number }}/head
+
+      - name: Run Codex
+        id: run_codex
+        uses: openai/codex-action@v1
+        with:
+          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+          prompt: |
+            This is PR #${{ github.event.pull_request.number }} for ${{ github.repository }}.
+            Base SHA: ${{ github.event.pull_request.base.sha }}
+            Head SHA: ${{ github.event.pull_request.head.sha }}
+
+            Review ONLY the changes introduced by the PR.
+            Suggest any improvements, potential bugs, security issues, or issues.
+            Be concise and specific in your feedback.
+
+            Pull request title and body:
+            ----
+            ${{ github.event.pull_request.title }}
+            ${{ github.event.pull_request.body }}
+
+  post_feedback:
+    runs-on: ubuntu-latest
+    needs: codex
+    if: needs.codex.outputs.final_message != ''
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Report Codex feedback
+        uses: actions/github-script@v7
+        env:
+          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: process.env.CODEX_FINAL_MESSAGE,
+            });

.gitignore

@@ -106,4 +106,7 @@ dmypy.json
 # Example files temp directories
 tmp/ 
 
-.DS_Store
+.DS_Store
+
+# Claude
+.claude/

DEVELOPMENT.md

@@ -0,0 +1,148 @@
+# Development Guide
+
+This guide covers how to set up and test the package locally before publishing.
+
+## Setup
+
+### Create a Virtual Environment
+
+```bash
+# Create a virtual environment
+python -m venv venv
+
+# Activate the virtual environment
+source venv/bin/activate  # On macOS/Linux
+# venv\Scripts\activate   # On Windows
+```
+
+### Install in Development Mode
+
+With the virtual environment activated, install the package with dev dependencies:
+
+```bash
+# Install in editable/development mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+This installs the package along with `python-dotenv` (for `.env` file support), `pytest`, `mypy`, `black`, and `flake8`.
+
+### Environment Variables
+
+Set the following environment variables for testing:
+
+```bash
+export FABRICATE_API_KEY="your-api-key"
+export FABRICATE_API_URL="https://fabricate.tonic.ai/api/v1"  # or your local instance
+```
+
+Or create a `.env` file (requires `python-dotenv`):
+
+```
+FABRICATE_API_KEY=your-api-key
+FABRICATE_API_URL=https://fabricate.tonic.ai/api/v1
+```
+
+## Testing
+
+### Quick Import Test
+
+Verify the module imports correctly:
+
+```bash
+python -c "from tonic_fabricate import generate, run_workflow, WorkflowResult; print('All imports work!')"
+```
+
+### Run the Examples
+
+The examples test the actual API calls:
+
+```bash
+# Test the generate function
+python examples/download.py
+
+# Test the workflow function
+python examples/workflow.py
+```
+
+### Interactive Testing
+
+```python
+from tonic_fabricate import run_workflow
+import os
+
+result = run_workflow(
+    database='your_database',
+    workspace='your_workspace',
+    workflow='your_workflow',
+    api_url=os.environ.get('FABRICATE_API_URL'),
+    on_progress=lambda p: print(p)
+)
+print(result.result)
+```
+
+## Code Quality
+
+### Install Dev Dependencies
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+### Type Checking
+
+```bash
+mypy tonic_fabricate/
+```
+
+### Linting
+
+```bash
+flake8 tonic_fabricate/
+```
+
+### Formatting
+
+```bash
+# Check formatting
+black --check tonic_fabricate/
+
+# Auto-format
+black tonic_fabricate/
+```
+
+## Pre-Publish Testing
+
+Before publishing to production PyPI, test with TestPyPI:
+
+```bash
+# Publish to TestPyPI
+./publish-test.sh
+
+# Install from TestPyPI to verify
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ tonic-fabricate==1.1.0
+
+# Test the installed package
+python -c "from tonic_fabricate import generate, run_workflow; print('Package works!')"
+```
+
+## Publishing
+
+See [publishing.md](publishing.md) for detailed publishing instructions.
+
+### Quick Reference
+
+```bash
+# Test publish
+./publish-test.sh
+
+# Production publish (after testing)
+./publish.sh
+```
+
+## Deactivating the Virtual Environment
+
+When you're done developing:
+
+```bash
+deactivate
+```

README.md

@@ -109,12 +109,80 @@ The client will automatically use the following environment variables if they ar
 - `FABRICATE_API_KEY`: Your Fabricate API key
 - `FABRICATE_API_URL`: The Fabricate API URL (defaults to https://fabricate.tonic.ai/api/v1)
 
+## Workflows
+
+Fabricate supports workflows that can perform custom operations and generate files. To run a workflow:
+
+```python
+from tonic_fabricate import run_workflow
+
+result = run_workflow(
+    # The workspace to use
+    workspace='Default',
+
+    # The name of the database
+    database='my_database',
+
+    # The name of the workflow to run
+    workflow='my_workflow',
+
+    # Optional: Parameters to pass to the workflow
+    params={
+        'message': 'Hello, world!',
+    },
+)
+
+# Access the workflow result
+print(f"Result: {result.result}")
+
+# Download generated files if any
+if result.task.files:
+    for file in result.task.files:
+        print(f"File: {file.name} ({file.size} bytes)")
+        result.download_file(file.id, f"./output/{file.name}")
+
+    # Or download all files at once
+    result.download_all_files('./output')
+```
+
+### Workflow Progress Tracking
+
+```python
+from tonic_fabricate import run_workflow
+
+def on_progress(data):
+    status = data.get('status', '')
+    message = data.get('message', '')
+    print(f"[{status}] {message}")
+
+result = run_workflow(
+    workspace='Default',
+    database='my_database',
+    workflow='my_workflow',
+    on_progress=on_progress
+)
+```
+
+### Workflow File Downloads
+
+You can also download workflow files directly using `download_workflow_file`:
+
+```python
+from tonic_fabricate import download_workflow_file
+
+download_workflow_file(
+    task_id='your-task-id',
+    file_id=123,
+    dest_path='./output/file.txt'
+)
+```
+
 ## Error Handling
 
 The client raises appropriate exceptions for various error conditions:
 
 ```python
-from tonic_fabricate import generate
+from tonic_fabricate import generate, run_workflow
 
 try:
     generate(
@@ -127,4 +195,15 @@ except ValueError as e:
     print(f"Invalid parameters: {e}")
 except Exception as e:
     print(f"Generation failed: {e}")
+
+try:
+    result = run_workflow(
+        workspace='Default',
+        database='my_database',
+        workflow='my_workflow'
+    )
+except ValueError as e:
+    print(f"Invalid parameters: {e}")
+except Exception as e:
+    print(f"Workflow failed: {e}")
 ```

examples/download.py

@@ -7,14 +7,10 @@
 import sys
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
 
-from tonic_fabricate import generate
+from dotenv import load_dotenv
+load_dotenv()
 
-# Load environment variables if python-dotenv is available
-try:
-    from dotenv import load_dotenv
-    load_dotenv()
-except ImportError:
-    pass
+from tonic_fabricate import generate
 
 def on_progress(data):
     """Progress callback function."""