openbox-temporal-sdk-python 1.0.0__tar.gz → 1.0.2__tar.gz

openbox_temporal_sdk_python-1.0.2/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch twine
+
+      - name: Verify version matches tag
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Error: Tag version ($TAG_VERSION) does not match package version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: $PKG_VERSION"
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

openbox_temporal_sdk_python-1.0.2/.github/workflows/sonarqube.yaml

@@ -0,0 +1,182 @@
+# .github/workflows/sonarqube.yml
+name: SonarQube
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write   
+  issues: write  
+
+jobs:
+  sonarqube:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest tests/ \
+            --cov=openbox \
+            --cov-report=xml:coverage.xml \
+            --cov-report=term-missing \
+            -v
+
+      - name: Compute Sonar project name
+        shell: bash
+        run: |
+          REPO_NAME="${{ github.event.repository.name }}"
+      
+          if [ "${GITHUB_REF_NAME}" = "staging" ]; then
+            echo "SONAR_PROJECT_NAME=${REPO_NAME}-staging" >> $GITHUB_ENV
+          else
+            echo "SONAR_PROJECT_NAME=${REPO_NAME}" >> $GITHUB_ENV
+          fi
+      
+      - name: SonarQube Scan
+        uses: SonarSource/sonarqube-scan-action@v5.3.0
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+        with:
+          args: >
+            -Dsonar.projectKey=${{ env.SONAR_PROJECT_NAME }}
+            -Dsonar.projectName="${{ env.SONAR_PROJECT_NAME }}"
+      
+      - name: Quality Gate
+        uses: SonarSource/sonarqube-quality-gate-action@v1.2.0
+        continue-on-error: true
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+        with:
+           pollingTimeoutSec: 600 
+
+
+      - name: Wait for quality gate
+        if: always()
+        run: sleep 30   
+
+      - name: Build SonarQube Quality Gate report 
+        if: always()
+        id: qg
+        env:
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_PROJECT_NAME: ${{ env.SONAR_PROJECT_NAME }}
+        run: |
+          set -euo pipefail
+      
+          HOST_TRIM="${SONAR_HOST_URL%/}"
+          TOKEN="${SONAR_TOKEN}"
+          PKEY="${SONAR_PROJECT_NAME}"   # projectKey
+          PNAME="${SONAR_PROJECT_NAME}"  # projectName hiển thị
+      
+          urlencode() { jq -nr --arg v "$1" '$v|@uri'; }
+      
+          PKEY_ENC="$(urlencode "$PKEY")"
+          API_URL="${HOST_TRIM}/api/qualitygates/project_status?projectKey=${PKEY_ENC}"
+      
+          JSON="$(curl -fsSL -u "${TOKEN}:" "$API_URL")"
+      
+          STATUS="$(jq -r '.projectStatus.status' <<<"$JSON")"                       # OK | WARN | ERROR
+          QG_NAME="$(jq -r '.projectStatus.qualityGate.name // "Default"' <<<"$JSON")"
+          if [ -z "${SONAR_HOST_URL:-}" ]; then
+            echo "::warning::SONAR_HOST_URL is empty"
+          fi
+          DASH_URL="${SONAR_HOST_URL}/dashboard?id=$(urlencode "$PKEY")"
+      
+          {
+            echo "### SonarQube Quality Gate: ${QG_NAME}"
+            echo
+            echo "- **Project**: ${PNAME}"
+            echo "- **Status**: **${STATUS}**"
+            echo "- **Detail**: [Open in SonarQube](${DASH_URL})"
+          } > qg.md
+      
+          cat qg.md >> "$GITHUB_STEP_SUMMARY"
+          echo "STATUS=${STATUS}"   >> "$GITHUB_ENV"
+          echo "QG_NAME=${QG_NAME}" >> "$GITHUB_ENV"
+          echo "PNAME=${PNAME}"     >> "$GITHUB_ENV"
+        
+      # (2) Upsert Issue cho
+      - name: Comment (or create) Issue with QG report
+        if: always() && env.STATUS != 'OK'
+        uses: actions/github-script@v7
+        env:
+          ISSUE_NUMBER: ${{ vars.SONAR_ISSUE_NUMBER }}      
+          SONAR_PROJECT_NAME: ${{ env.SONAR_PROJECT_NAME }}  
+          QG_NAME: ${{ env.QG_NAME }}
+          STATUS: ${{ env.STATUS }}
+        with:
+          script: |
+            const fs = require('fs');
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+      
+            const body = fs.readFileSync('qg.md', 'utf8');
+            const projectName = process.env.SONAR_PROJECT_NAME;
+            const status = process.env.STATUS;
+            const qgName = process.env.QG_NAME;
+      
+
+            const stableTitle = `SonarQube QG • ${projectName}`;
+
+            const displayTitle = `${stableTitle} — ${qgName} (${status})`;
+      
+            let issueNumber = process.env.ISSUE_NUMBER ? Number(process.env.ISSUE_NUMBER) : null;
+      
+            if (!issueNumber) {
+              const { data: search } = await github.rest.search.issuesAndPullRequests({
+                q: `repo:${owner}/${repo} is:issue state:open in:title "${stableTitle}" label:sonarqube`
+              });
+      
+              if (search.total_count > 0) {
+                issueNumber = search.items[0].number;
+                core.info(`Found existing issue #${issueNumber} for project "${projectName}".`);
+              }
+            }
+      
+            if (issueNumber) {
+              try {
+                await github.rest.issues.update({ owner, repo, issue_number: issueNumber, title: stableTitle });
+              } catch (e) {
+                core.warning(`Failed to update title to stableTitle: ${e.message}`);
+              }
+              await github.rest.issues.createComment({ owner, repo, issue_number: issueNumber, body });
+              core.info(`Appended comment to issue #${issueNumber}`);
+            } else {
+              const { data: issue } = await github.rest.issues.create({
+                owner, repo,
+                title: stableTitle,
+                body,
+                labels: ['sonarqube','quality-gate']
+              });
+              core.info(`Created issue #${issue.number} for project "${projectName}"`);
+            }
+
+      - name: Fail job when Quality Gate not OK
+        if: env.STATUS != 'OK'
+        run: |
+          echo "::error title=Quality Gate Failed::STATUS=${{ env.STATUS }} (expected OK)"
+          exit 1

{openbox_temporal_sdk_python-1.0.0 → openbox_temporal_sdk_python-1.0.2}/.gitignore

@@ -33,3 +33,10 @@ htmlcov/
 # OS
 .DS_Store
 Thumbs.db
+
+.opencode/
+AGENTS.md
+
+.claude/
+CLAUDE.md
+plans/

openbox_temporal_sdk_python-1.0.2/.repomixignore

@@ -0,0 +1,22 @@
+docs/*
+plans/*
+assets/*
+dist/*
+coverage/*
+build/*
+ios/*
+android/*
+tests/*
+__tests__/*
+__pycache__/*
+node_modules/*
+
+.opencode/*
+.claude/*
+.serena/*
+.pnpm-store/*
+.github/*
+.dart_tool/*
+.idea/*
+.husky/*
+.venv/*

openbox_temporal_sdk_python-1.0.2/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: openbox-temporal-sdk-python
+Version: 1.0.2
+Summary: OpenBox SDK - Governance and observability for Temporal workflows
+Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
+Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
+Project-URL: Repository, https://github.com/OpenBox-AI/temporal-sdk-python.git
+Project-URL: Issues, https://github.com/OpenBox-AI/temporal-sdk-python/issues
+Project-URL: Changelog, https://github.com/OpenBox-AI/temporal-sdk-python/blob/main/CHANGELOG.md
+Author-email: OpenBox Team <tino@openbox.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: governance,hitl,human-in-the-loop,observability,opentelemetry,temporal,workflow
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: httpx<1,>=0.28.0
+Requires-Dist: mysql-connector-python>=8.0.0
+Requires-Dist: opentelemetry-api>=1.38.0
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-mysql>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-pymongo>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-pymysql>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-redis>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-requests>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-urllib3>=0.59b0
+Requires-Dist: opentelemetry-instrumentation-urllib>=0.59b0
+Requires-Dist: opentelemetry-sdk>=1.38.0
+Requires-Dist: psycopg2-binary>=2.9.10
+Requires-Dist: pymongo>=4.0.0
+Requires-Dist: pymysql>=1.0.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: temporalio<2,>=1.8.0
+Description-Content-Type: text/markdown
+
+# OpenBox SDK for Temporal Workflows
+
+OpenBox SDK provides **governance and observability** for Temporal workflows by capturing workflow/activity lifecycle events, HTTP telemetry, database queries, and file operations, then sending them to OpenBox Core for policy evaluation.
+
+**Key Features:**
+- 6 event types (WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted)
+- 5-tier verdict system (ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK, HALT)
+- HTTP/Database/File I/O instrumentation via OpenTelemetry
+- Guardrails: Input/output validation and redaction
+- Human-in-the-loop approval with expiration handling
+- Zero-code setup via `create_openbox_worker()` factory
+
+---
+
+## Installation
+
+```bash
+pip install openbox-temporal-sdk-python
+```
+
+**Requirements:**
+- Python 3.9+
+- Temporal SDK 1.8+
+- OpenTelemetry API/SDK 1.38.0+
+
+---
+
+## Quick Start
+
+Use the `create_openbox_worker()` factory for simple integration:
+
+```python
+import os
+from openbox import create_openbox_worker
+
+worker = create_openbox_worker(
+    client=client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    # OpenBox config
+    openbox_url=os.getenv("OPENBOX_URL"),
+    openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+)
+
+await worker.run()
+```
+
+The factory automatically:
+1. Validates the API key
+2. Creates span processor
+3. Sets up OpenTelemetry instrumentation
+4. Creates governance interceptors
+5. Adds `send_governance_event` activity
+6. Returns fully configured Worker
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+OPENBOX_URL=http://localhost:8086
+OPENBOX_API_KEY=obx_test_key_1
+OPENBOX_GOVERNANCE_TIMEOUT=30.0
+OPENBOX_GOVERNANCE_POLICY=fail_open  # or fail_closed
+```
+
+### Factory Function Parameters
+
+```python
+worker = create_openbox_worker(
+    client=client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+
+    # OpenBox config
+    openbox_url="http://localhost:8086",
+    openbox_api_key="obx_test_key_1",
+    governance_timeout=30.0,
+    governance_policy="fail_open",
+
+    # Event filtering
+    send_start_event=True,
+    send_activity_start_event=True,
+    skip_workflow_types={"InternalWorkflow"},
+    skip_activity_types={"send_governance_event"},
+    skip_signals={"heartbeat"},
+
+    # Database instrumentation
+    instrument_databases=True,
+    db_libraries={"psycopg2", "sqlalchemy"},  # None = all available
+    sqlalchemy_engine=engine,  # pass pre-existing engine for query capture
+
+    # File I/O instrumentation
+    instrument_file_io=False,  # disabled by default
+
+    # Standard Worker options (all supported)
+    activity_executor=my_executor,
+    max_concurrent_activities=10,
+)
+```
+
+---
+
+## Governance Verdicts
+
+OpenBox Core returns a verdict indicating what action the SDK should take.
+
+| Verdict | Behavior |
+|---------|----------|
+| `ALLOW` | Continue execution normally |
+| `CONSTRAIN` | Log constraints, continue |
+| `REQUIRE_APPROVAL` | Pause, poll for human approval |
+| `BLOCK` | Raise error, stop activity |
+| `HALT` | Raise error, terminate workflow |
+
+**v1.0 Backward Compatibility:**
+- `"continue"` → `ALLOW`
+- `"stop"` → `HALT`
+- `"require-approval"` → `REQUIRE_APPROVAL`
+
+---
+
+## Event Types
+
+| Event | Trigger | Captured Fields |
+|-------|---------|-----------------|
+| WorkflowStarted | Workflow begins | workflow_id, run_id, workflow_type, task_queue |
+| WorkflowCompleted | Workflow succeeds | workflow_id, run_id, workflow_type |
+| WorkflowFailed | Workflow fails | workflow_id, run_id, workflow_type, error |
+| SignalReceived | Signal received | workflow_id, signal_name, signal_args |
+| ActivityStarted | Activity begins | activity_id, activity_type, activity_input |
+| ActivityCompleted | Activity ends | activity_id, activity_type, activity_input, activity_output, spans, status, duration |
+
+---
+
+## Guardrails (Input/Output Redaction)
+
+OpenBox Core can validate and redact sensitive data before/after activity execution:
+
+```python
+# Request
+{
+  "verdict": "allow",
+  "guardrails_result": {
+    "input_type": "activity_input",
+    "redacted_input": {"prompt": "[REDACTED]", "user_id": "123"},
+    "validation_passed": true,
+    "reasons": []
+  }
+}
+
+# If validation fails:
+{
+  "validation_passed": false,
+  "reasons": [
+    {"type": "pii", "field": "email", "reason": "Contains PII"}
+  ]
+}
+```
+
+---
+
+## Error Handling
+
+Configure error policy via `on_api_error`:
+
+| Policy | Behavior |
+|--------|----------|
+| `fail_open` (default) | If governance API fails, allow workflow to continue |
+| `fail_closed` | If governance API fails, terminate workflow |
+
+---
+
+## Supported Instrumentation
+
+### HTTP Libraries
+- `httpx` (sync + async) - full body capture
+- `requests` - full body capture
+- `urllib3` - full body capture
+- `urllib` - request body only
+
+### Databases
+- PostgreSQL: `psycopg2`, `asyncpg`
+- MySQL: `mysql-connector-python`, `pymysql`
+- MongoDB: `pymongo`
+- Redis: `redis`
+- ORM: `sqlalchemy`
+
+**SQLAlchemy Note:** If your SQLAlchemy engine is created before `create_openbox_worker()` runs (e.g., at module import time), you must pass it via the `sqlalchemy_engine` parameter. Without this, `SQLAlchemyInstrumentor` only patches future `create_engine()` calls and won't capture queries on pre-existing engines.
+
+```python
+from db.engine import engine
+
+worker = create_openbox_worker(
+    ...,
+    db_libraries={"psycopg2", "sqlalchemy"},
+    sqlalchemy_engine=engine,
+)
+```
+
+### File I/O
+- `open()`, `read()`, `write()`, `readline()`, `readlines()`
+- Skips system paths (`/dev/`, `/proc/`, `/sys/`, `__pycache__`)
+
+---
+
+## Architecture
+
+See [System Architecture](./docs/system-architecture.md) for detailed component design.
+
+**High-Level Flow:**
+
+```
+Workflow/Activity → Interceptors → Span Processor → OpenBox Core API
+                                                    ↓
+                                            Returns Verdict
+                                                    ↓
+                                    (ALLOW, BLOCK, HALT, etc.)
+```
+
+---
+
+## Advanced Usage
+
+For manual control, import individual components:
+
+```python
+from openbox import (
+    initialize,
+    WorkflowSpanProcessor,
+    GovernanceInterceptor,
+    GovernanceConfig,
+)
+from openbox.otel_setup import setup_opentelemetry_for_governance
+from openbox.activity_interceptor import ActivityGovernanceInterceptor
+from openbox.activities import send_governance_event
+
+# 1. Initialize SDK
+initialize(api_url="http://localhost:8086", api_key="obx_test_key_1")
+
+# 2. Create span processor
+span_processor = WorkflowSpanProcessor(
+    ignored_url_prefixes=["http://localhost:8086"]
+)
+
+# 3. Setup OTel instrumentation
+setup_opentelemetry_for_governance(
+    span_processor,
+    sqlalchemy_engine=engine,  # optional: instrument pre-existing engine
+)
+
+# 4. Create governance config
+config = GovernanceConfig(
+    on_api_error="fail_closed",
+    api_timeout=30.0,
+)
+
+# 5. Create interceptors
+workflow_interceptor = GovernanceInterceptor(
+    api_url="http://localhost:8086",
+    api_key="obx_test_key_1",
+    span_processor=span_processor,
+    config=config,
+)
+
+activity_interceptor = ActivityGovernanceInterceptor(
+    api_url="http://localhost:8086",
+    api_key="obx_test_key_1",
+    span_processor=span_processor,
+    config=config,
+)
+
+# 6. Create worker
+from temporalio.worker import Worker
+worker = Worker(
+    client=client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity, send_governance_event],
+    interceptors=[workflow_interceptor, activity_interceptor],
+)
+```
+
+---
+
+## Documentation
+
+- **[Project Overview & PDR](./docs/project-overview-pdr.md)** - Requirements, features, constraints
+- **[System Architecture](./docs/system-architecture.md)** - Component design, data flows, security
+- **[Codebase Summary](./docs/codebase-summary.md)** - Code structure and component details
+- **[Code Standards](./docs/code-standards.md)** - Coding conventions and best practices
+- **[Project Roadmap](./docs/project-roadmap.md)** - Future enhancements and timeline
+
+---
+
+## Testing
+
+The SDK includes comprehensive test coverage with 10 test files:
+
+```bash
+pytest tests/
+```
+
+Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_otel_setup.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
+
+---
+
+## License
+
+MIT License - See LICENSE file for details
+
+---
+
+## Support
+
+- **Issues:** GitHub Issues
+- **Documentation:** See `./docs/`
+
+---
+
+**Version:** 1.0.2 | **Last Updated:** 2026-02-12