tactus 0.5.0__tar.gz

tactus-0.5.0/.claude/agents.md

@@ -0,0 +1,47 @@
+# AI Agent Guidelines
+
+## Semantic Release & Versioning
+
+This project uses **semantic-release** for automated versioning and releases.
+
+### Commit Message Format (Conventional Commits)
+
+- `feat:` → MINOR version bump (0.1.0 → 0.2.0) - use sparingly
+- `fix:` → PATCH version bump (0.1.0 → 0.1.1)
+- `docs:`, `test:`, `chore:`, `refactor:`, `style:` → No version bump
+
+### Important: Version Escalation Awareness
+
+**Do NOT use `feat:` for every new feature.** Be conscious of version escalation:
+
+- Group related changes into meaningful releases
+- Use `chore:` or `refactor:` for internal improvements that don't add user-facing features
+- Reserve `feat:` for significant new capabilities that warrant a minor version bump
+- Consider if the change truly adds value that users should know about in the changelog
+
+### Examples
+
+**Good:**
+```
+feat: add AWS Bedrock provider support
+fix: handle missing config file gracefully
+chore: update dependencies
+refactor: simplify error handling logic
+```
+
+**Avoid:**
+```
+feat: add helper function           # Use chore:
+feat: improve internal logic        # Use refactor:
+feat: add logging statement         # Use chore:
+```
+
+### Release Process
+
+Releases happen automatically on push to main. The CI runs:
+1. Linting (ruff), formatting (black)
+2. Tests (pytest + behave, excluding integration tests)
+3. Semantic-release (if tests pass)
+4. Publishes to PyPI
+
+Monitor with: `gh run watch`

tactus-0.5.0/.github/workflows/desktop-release.yml

@@ -0,0 +1,83 @@
+name: Desktop Release
+
+on:
+  push:
+    tags:
+      - 'desktop-v*'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, windows-latest, ubuntu-latest]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyinstaller
+          pip install -e .
+
+      - name: Install Node dependencies (Desktop)
+        working-directory: ./tactus-desktop
+        run: npm install
+
+      - name: Build Frontend
+        working-directory: ./tactus-desktop
+        run: npm run build:frontend
+
+      - name: Build Backend
+        working-directory: ./tactus-desktop
+        run: npm run build:backend
+
+      - name: Build Electron
+        working-directory: ./tactus-desktop
+        run: npm run build
+
+      - name: Package Application (macOS)
+        if: matrix.os == 'macos-latest'
+        working-directory: ./tactus-desktop
+        run: npm run package:mac
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Package Application (Windows)
+        if: matrix.os == 'windows-latest'
+        working-directory: ./tactus-desktop
+        run: npm run package:win
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Package Application (Linux)
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: ./tactus-desktop
+        run: npm run package:linux
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ matrix.os }}-build
+          path: tactus-desktop/dist-electron/*
+
+      - name: Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: tactus-desktop/dist-electron/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

tactus-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  quality-checks:
+    name: Quality Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff linting
+        run: ruff check tactus/ tests/ features/steps/
+
+      - name: Run black formatting check
+        run: black --check tactus/ tests/ features/steps/
+
+      - name: Run pytest tests
+        run: pytest tests/ -v --tb=short -m "not integration"
+
+      - name: Run behave BDD tests
+        run: behave
+
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    needs: quality-checks
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install python-semantic-release
+        run: |
+          python -m pip install --upgrade pip
+          pip install python-semantic-release
+
+      - name: Python Semantic Release
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          semantic-release version
+          semantic-release publish
+
+      - name: Publish to PyPI
+        if: success()
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          pip install twine
+          twine upload dist/*

tactus-0.5.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.env
+.venv
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.pytest_cache/
+.ruff_cache/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Node / frontend
+node_modules/
+.vite/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Tactus specific
+.tac/config.yml
+progress.output
+.tactus/config.yml

tactus-0.5.0/AGENTS.md

@@ -0,0 +1,221 @@
+# Instructions for Coding Agents
+
+This document provides guidelines for AI coding agents working on the Tactus project.
+
+## Pre-Commit Checklist
+
+**CRITICAL**: Before committing any changes, you MUST run the complete test and linting suite:
+
+```bash
+# 1. Run unit tests
+pytest tests/ -x -k "not test_real_execution"
+
+# 2. Run BDD behavior tests
+behave --summary
+
+# 3. Check code style with ruff (no uncommitted code should have ruff errors)
+ruff check .
+
+# 4. Format code with black
+black tactus tactus-ide/backend features/steps tests
+
+# 5. Verify all checks pass again
+ruff check .
+black tactus tactus-ide/backend features/steps tests --check
+```
+
+Only commit when ALL of the above pass. Do not skip this step or commit before running these checks.
+
+## Reference Documentation
+
+- **[SPECIFICATION.md](SPECIFICATION.md)**: The official specification for the Tactus domain-specific language. Refer to this document for the definitive guide on DSL syntax, semantics, and behavior.
+- **[IMPLEMENTATION.md](IMPLEMENTATION.md)**: Maps the specification to the actual codebase implementation. Shows where each feature is implemented, what's complete, and what's missing relative to the specification. Use this to understand the current implementation status when working on features.
+
+## Multi-Model and Multi-Provider Support
+
+**IMPORTANT**: Tactus now supports multiple LLM providers and models:
+
+- **Providers**: `openai` and `bedrock` are supported
+- **Provider is REQUIRED**: Every agent must specify `provider:` (either directly or via `default_provider:` at procedure level)
+- **Multiple models**: Different agents can use different models (e.g., GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet)
+- **Model parameters**: Supports model-specific parameters like `temperature`, `max_tokens`, `openai_reasoning_effort`
+
+Example:
+```yaml
+agents:
+  openai_agent:
+    provider: openai
+    model:
+      name: gpt-4o
+      temperature: 0.7
+    system_prompt: "..."
+    tools: [done]
+  
+  bedrock_agent:
+    provider: bedrock
+    model: anthropic.claude-3-5-sonnet-20240620-v1:0
+    system_prompt: "..."
+    tools: [done]
+```
+
+## Production Readiness
+
+**IMPORTANT**: Tactus is **NOT** ready for production. It is in early development (Alpha status).
+
+### Do NOT:
+- Declare that Tactus is "ready for production"
+- Claim that features are "production-ready"
+- State that the project is "complete" or "finished"
+- Use phrases like "ready to use in production" or "production-ready"
+
+### Do:
+- Focus on testing and verification
+- Run existing tests before declaring changes complete
+- Verify that implementations actually work as intended
+- Acknowledge limitations and incomplete features
+- Suggest improvements and note areas that need work
+
+## Semantic Release and Changelog
+
+**IMPORTANT**: This project uses Semantic Release to automatically manage versioning and the changelog.
+
+- **Do NOT manually edit `CHANGELOG.md`**. It is generated and updated automatically by the release workflow.
+- **Do NOT add `CHANGELOG.md` to `.gitignore`**. It must be tracked in the repository so the release bot can commit updates to it.
+- **Do NOT delete or truncate `CHANGELOG.md`**.
+- Ensure your commit messages follow the [Angular Commit Message Convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit) (e.g., `feat: ...`, `fix: ...`, `docs: ...`) so that Semantic Release can correctly generate the changelog.
+
+## Parser Generation Requirements
+
+**IMPORTANT**: Tactus uses ANTLR4 to generate parsers from the Lua grammar for both Python and TypeScript.
+
+### Requirements for Parser Generation
+
+**Docker is REQUIRED** for generating parsers:
+- Parser generation uses ANTLR4 which requires Java
+- We use Docker to avoid requiring Java installation on developer machines
+- Docker image: `eclipse-temurin:17-jre`
+
+**When to regenerate parsers:**
+- Only when modifying the Lua grammar files
+- Generated parsers are committed to version control
+- End users don't need Docker or Java
+
+**How to regenerate parsers:**
+```bash
+# Ensure Docker is running
+make generate-parsers
+
+# Or generate individually:
+make generate-python-parser
+make generate-typescript-parser
+```
+
+**Generated files (committed to repo):**
+- `tactus/validation/generated/*.py` - Python parser
+- `tactus-ide/frontend/src/validation/generated/*.ts` - TypeScript parser
+
+## Tactus IDE Development
+
+When working on the Tactus IDE:
+
+### Architecture: Hybrid Validation
+
+The IDE uses a two-layer validation approach for optimal performance and user experience:
+
+**Layer 1: TypeScript Parser (Client-Side)**
+- Location: `tactus-ide/frontend/src/validation/`
+- ANTLR-generated from same `Lua.g4` grammar as Python parser
+- Purpose: Instant syntax validation (< 10ms)
+- Runs in browser, no backend needed
+- Provides immediate feedback as user types
+- Works offline
+
+**Layer 2: Python LSP (Backend)**
+- Location: `tactus-ide/backend/`
+- Uses existing `TactusValidator` from `tactus/validation/`
+- Purpose: Semantic validation and intelligence
+- Debounced (300ms) to reduce load
+- Provides completions, hover, signature help
+- Cross-reference validation
+
+### Why Hybrid?
+
+1. **Performance**: Syntax errors appear instantly (no network delay)
+2. **Offline**: Basic editing works without backend
+3. **Intelligence**: LSP adds semantic features when available
+4. **Scalability**: Reduces backend load (syntax is client-side)
+5. **User Experience**: No lag, no waiting for validation
+
+### Backend (Python LSP Server)
+- Location: `tactus-ide/backend/`
+- Uses existing `TactusValidator` from `tactus/validation/`
+- Implements LSP protocol for language intelligence
+- Flask server provides HTTP and WebSocket endpoints
+- Focus on semantic validation, not syntax (handled client-side)
+
+### Frontend (React + Monaco)
+- Location: `tactus-ide/frontend/`
+- Monaco Editor for code editing (same as VS Code)
+- TypeScript parser for instant syntax validation
+- LSP client communicates with Python backend via WebSocket
+- Can be packaged as Electron app
+
+### Testing IDE Features
+- TypeScript parser: `cd tactus-ide/frontend && npm test`
+- Backend LSP: `pytest tactus-ide/backend/` (when tests are added)
+- Integration: Test with example `.tac` files
+- Verify both layers work independently and together
+
+### Running the IDE
+
+```bash
+# Terminal 1: Backend
+cd tactus-ide/backend
+pip install -r requirements.txt
+python app.py
+
+# Terminal 2: Frontend
+cd tactus-ide/frontend
+npm install
+npm run dev
+```
+
+### Electron Packaging
+The IDE is designed to run as a desktop application:
+- Backend runs as subprocess or separate service
+- Frontend uses Electron's IPC for file operations
+- No dependency on browser-specific APIs
+- Hybrid validation works in Electron environment
+
+## Testing Requirements
+
+Before declaring any change complete:
+
+1. **Run existing tests**: Use `pytest` to verify no regressions
+2. **Test the specific feature**: Create or update tests for new functionality
+3. **Verify imports**: Ensure all imports resolve correctly
+4. **Check for errors**: Run linters and fix any issues
+5. **Test parser changes**: If grammar modified, run `make test-parsers`
+
+## Code Quality
+
+- Follow existing code patterns and style
+- Add appropriate logging for debugging
+- Include docstrings for public APIs
+- Handle errors gracefully with proper exception types
+- Keep implementations simple and maintainable
+
+## Project Status
+
+Tactus is a standalone workflow engine extracted from a larger project. It is:
+- In active development
+- Missing some features (noted in code with TODO comments)
+- Subject to API changes
+- Not yet suitable for production use
+
+When working on Tactus, focus on:
+- Making incremental improvements
+- Fixing bugs and issues
+- Adding missing functionality
+- Improving documentation
+- Writing and maintaining tests

tactus-0.5.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.5.0 (2025-12-13)
+
+
+## v0.4.0 (2025-12-13)
+
+
+## v0.3.0 (2025-12-12)
+
+### Bug Fixes
+
+- Add missing fallback logging in LogPrimitive.debug()
+  ([`26fc8d7`](https://github.com/AnthusAI/Tactus/commit/26fc8d74794afd38f9b421b4cffcf090f5b74340))
+
+- Resolve ruff and black linter issues
+  ([`4091d41`](https://github.com/AnthusAI/Tactus/commit/4091d416b00293f8f60d0a2a3997ab4a7c055172))
+
+### Chores
+
+- Add .tactus/config.yml to gitignore
+  ([`bcc75f6`](https://github.com/AnthusAI/Tactus/commit/bcc75f66fb901c3845807663d816bcc5194c6026))
+
+### Code Style
+
+- Apply black formatting to all files
+  ([`7f76e75`](https://github.com/AnthusAI/Tactus/commit/7f76e757a59687a12397032ba089f3eb40d1e99a))
+
+### Features
+
+- **BDD**: Tactus is BDD at the core. 🤘
+  ([`66e8fb7`](https://github.com/AnthusAI/Tactus/commit/66e8fb7786a30e1a494d7339c4e473d95767288f))
+
+### Refactoring
+
+- Remove deprecated description() construct from DSL
+  ([`380ac5f`](https://github.com/AnthusAI/Tactus/commit/380ac5f164d71ba48bd6462644a8f958a50a4053))
+
+
+## v0.2.1 (2025-12-12)
+
+### Bug Fixes
+
+- Add PyPI upload step to release workflow
+  ([`1849407`](https://github.com/AnthusAI/Tactus/commit/1849407c1b14683bc137390bab08173118664557))
+
+
+## v0.2.0 (2025-12-11)
+
+### Documentation
+
+- Add AI agent guidelines for semantic release
+  ([`daa1736`](https://github.com/AnthusAI/Tactus/commit/daa173665f888dce5de423e72f6dab909b95b632))
+
+### Features
+
+- Migrate to pure Lua DSL and add Electron-based IDE
+  ([`5d91807`](https://github.com/AnthusAI/Tactus/commit/5d91807e770bbb5f6203407239eb9da8ee44aac8))
+
+### Breaking Changes
+
+- Workflow format changed from YAML+Lua (.tyml) to pure Lua DSL (.tac.lua)
+
+
+## v0.1.0 (2025-12-11)
+
+- Initial Release
+
+## v0.0.0 (2025-12-11)
+
+- Initial Release