Metadata-Version: 2.4
Name: nexora-tasks-server
Version: 1.0.0
Summary: Nexora Tasks server — deploy, schedule, and manage task workflows with a web UI, webhooks, and REST API
Project-URL: Documentation, https://github.com/Tessi-Wekey/tasks-platform#readme
Project-URL: Repository, https://github.com/Tessi-Wekey/tasks-platform
Project-URL: Issues, https://github.com/Tessi-Wekey/tasks-platform/issues
Project-URL: Changelog, https://github.com/Tessi-Wekey/tasks-platform/blob/main/CHANGELOG.md
Author-email: Cinco AI <dev@cinco.ai>
License: MIT
Keywords: async,fastapi,observability,scheduling,server,task,webhooks,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: apscheduler>=3.11.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: nexora-tasks-sdk>=1.0.0
Requires-Dist: packaging>=24.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: slowapi>=0.1.9
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: all
Requires-Dist: aiobotocore>=3.4.0; extra == 'all'
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: elasticsearch[async]>=9.0.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-elasticsearch>=0.48b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: boto3<2.0,>=1.35; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: elasticsearch
Requires-Dist: elasticsearch[async]>=9.0.0; extra == 'elasticsearch'
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-elasticsearch>=0.48b0; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'observability'
Provides-Extra: s3
Requires-Dist: aiobotocore>=3.4.0; extra == 's3'
Requires-Dist: boto3>=1.34.0; extra == 's3'
Provides-Extra: test
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: playwright>=1.40.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-playwright>=0.4.0; extra == 'test'
Requires-Dist: pytest>=8.3.0; extra == 'test'
Description-Content-Type: text/markdown

# Task Framework Server

Production-grade task execution server with web UI, webhooks, scheduling, and multi-task support.

## Installation

```bash
pip install nexora-tasks-server
```

## Quick Start

### Start the server

```bash
task-server --port 3000 --base-path ./data
```

Or use environment variables:

```bash
export PORT=3000
export BASE_PATH=/var/lib/task-server
export API_KEYS=your-api-key
export ADMIN_API_KEYS=your-admin-key
python -m task_framework_server.server
```

### Access

| Endpoint | Description |
|----------|-------------|
| `http://localhost:3000/ui` | Web Dashboard |
| `http://localhost:3000/docs` | OpenAPI Documentation |
| `http://localhost:3000/health` | Health Check |
| `http://localhost:3000/metrics` | Prometheus Metrics |

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3000` | Server port |
| `BASE_PATH` | `./data` | Base path for data storage |
| `API_KEYS` | — | Comma-separated API keys for client auth |
| `ADMIN_API_KEYS` | — | Comma-separated admin API keys |
| `STORAGE_TYPE` | `file` | Record/database backend: `file` or `elasticsearch` |
| `FILE_STORAGE_TYPE` | `local` | File storage backend: `local` or `s3` |
| `LOG_LEVEL` | `INFO` | Logging level |

### S3 Storage (optional)

```bash
export FILE_STORAGE_TYPE=s3
export S3_BUCKET=my-task-artifacts
export S3_REGION=eu-west-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
```

### Elasticsearch (optional)

```bash
export STORAGE_TYPE=elasticsearch
export ELASTICSEARCH_HOSTS=http://localhost:9200
```

## Deployment

### Docker

```bash
docker build -t task-server .
docker run -p 3000:3000 \
  -e API_KEYS=your-key \
  -e ADMIN_API_KEYS=your-admin-key \
  -v ./data:/data \
  task-server
```

### Docker Compose

```bash
docker-compose up -d
```

Pre-configured variants:
- `docker-compose.yml` — Basic setup
- `docker-compose.elasticsearch.yml` — With Elasticsearch
- `docker-compose.cloud.yml` — Cloud-ready with S3
- `docker-compose.standalone.yml` — Standalone mode

## API Overview

### Task Management (Admin)

```bash
# Deploy a task
curl -X POST http://localhost:3000/admin/tasks \
  -H "X-Admin-API-Key: your-admin-key" \
  -F "file=@my-task-1.0.0.zip"

# List deployed tasks
curl http://localhost:3000/admin/tasks \
  -H "X-Admin-API-Key: your-admin-key"
```

### Thread Execution

```bash
# Create and run a thread
curl -X POST http://localhost:3000/threads \
  -H "X-API-Key: your-key" \
  -H "X-App-Id: my-app" \
  -H "X-User-Id: user-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "sync", "inputs": [{"kind": "text", "text": "Hello"}]}'

# Get thread status
curl http://localhost:3000/threads/{thread_id} \
  -H "X-API-Key: your-key"

# Pause/Resume
curl -X POST http://localhost:3000/threads/{thread_id}:pause \
  -H "X-API-Key: your-key"
curl -X POST http://localhost:3000/threads/{thread_id}:resume \
  -H "X-API-Key: your-key"
```

### Webhooks

```bash
# Create a webhook
curl -X POST http://localhost:3000/webhooks \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/task-events",
    "events": ["thread.succeeded", "thread.failed"],
    "secret": "webhook-signing-secret"
  }'
```

### Schedules

```bash
# Create a schedule
curl -X POST http://localhost:3000/schedules \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "my-task",
    "cron": "0 8 * * MON",
    "timezone": "Europe/Paris",
    "inputs": [{"kind": "text", "text": "Weekly run"}]
  }'
```

## Features

- **Multi-task deployment** with isolated code + venv per task
- **Worker subprocess isolation** with JSON Lines IPC
- **Progress, pause, resume, cancel** — cooperative task control
- **Python & Node.js** task runtimes
- **Web Dashboard** — full CRUD for all resources
- **Webhook system** — HMAC-signed, scoped, with delivery tracking
- **Cron scheduling** — with concurrency policies
- **Artifact management** — local or S3 storage
- **Credential vault** — AES-encrypted secret storage
- **Proxy mode** — route to multiple task servers
- **Prometheus metrics** — request counts, durations, thread states
- **Idempotency** — duplicate request detection

## Development

```bash
# Clone and setup
git clone https://github.com/Tessi-Wekey/tasks-platform.git
cd task-framework
uv sync

# Run server tests
uv run --package nexora-tasks-server pytest packages/server/tests/ -v

# Start dev server
uv run --package nexora-tasks-server python -m task_framework_server.server
```

## License

MIT
