A cron-based scheduler that dynamically synthesizes and executes discrepancy detection projects. Cricket acts as a meta-scheduler that reads project configurations and rules from a database, generates executable detector code on-the-fly using Jinja2 templates, and runs them according to their cron schedules.

• Overview
• Architecture
• Features
• Capabilities
• Limitations
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the Service
• API Reference
• Database Schema
• Dependencies
• Docker Deployment
• Development

Cricket is a discrepancy detection orchestrator designed to:

1. Fetch project configurations and rules from a PostgreSQL database
2. Schedule project executions using cron expressions with timezone support
3. Synthesize executable Python detector code from templates and rule definitions
4. Execute generated detectors as isolated subprocess runs
5. Report discrepancy findings to a configured endpoint (Enliq)
6. Monitor execution status, history, and statistics via REST API

┌─────────────────────────────────────────────────────────────────────┐
│                        Cricket Runner Manager                        │
├──────────────────┬────────────────────┬─────────────────────────────┤
│    Scheduler     │      Executor      │         API                 │
│  (Cron Queue)    │ (Code Synthesizer) │    (FastAPI/Swagger)        │
├──────────────────┼────────────────────┼─────────────────────────────┤
│ - Priority Queue │ - Template Render  │ - Health Check              │
│ - Timezone Aware │ - Dependency Scan  │ - Queue Status              │
│ - Refresh Loop   │ - Subprocess Run   │ - Execution History         │
└──────────────────┴────────────────────┴─────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   PostgreSQL    │
                    │   Database      │
                    └─────────────────┘

1. Startup: Scheduler loads active projects from database into a min-heap priority queue
2. Scheduling: Every check_interval seconds, scheduler checks if the next project is due
3. Execution:
   • Fetch discrepancy rules for the project
   • Generate detector code using Jinja2 templates
   • Run the generated project via uv run python main.py
   • Capture exit code, stdout, stderr
   • Record execution result in database
4. Rescheduling: After execution, calculate next run time and re-add to queue

• ✅ Cron-based Scheduling - Full cron expression support with timezone awareness
• ✅ Dynamic Code Generation - Synthesize Python detector projects from templates
• ✅ Dependency Detection - Automatically extract and install required packages
• ✅ Multiple Data Sources - SQL databases, REST APIs, or manual data upload
• ✅ Execution Isolation - Each detector runs as an isolated subprocess
• ✅ Concurrent Execution Control - Configurable per-project concurrency limits
• ✅ Execution History - Full audit trail of all executions with timing and status
• ✅ RESTful Monitoring API - Swagger-documented endpoints for operations
• ✅ Health Checks - Built-in health endpoint for container orchestration
• ✅ Graceful Shutdown - Proper signal handling for clean termination

• Python 3.12+
• PostgreSQL database
• uv package manager (astral-sh/uv)

# Clone the repository
git clone <repository-url>
cd loodos-arge-normx-cricket

# Install dependencies using uv
uv sync

Create a .env file in the project root:

# Database connection
DATABASE_URL=postgresql://user:password@localhost:5432/cricket

# Report destination (optional)
ENLIQ_REPORT_URL=https://api.enliq.io/v1/reports

# Scheduler settings
MAX_QUEUE_SIZE=10
SCHEDULER_CHECK_INTERVAL=60.0

# Executor settings
EXECUTION_TIMEOUT=600
WORK_DIR=/tmp/cricket-projects

# API settings
API_HOST=0.0.0.0
API_PORT=8080

# Using the CLI entry point
uv run cricket

# Or directly with uvicorn
uv run uvicorn main:app --host 0.0.0.0 --port 8080

# Development with auto-reload
uv run uvicorn main:app --reload

Access the API documentation at:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI JSON: http://localhost:8080/openapi.json

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "runner_active": true,
  "projects_in_queue": 5,
  "currently_executing": null,
  "last_check": "2026-01-09T10:30:00Z"
}

curl http://localhost:8080/queue

Response:

[
  {
    "project_id": "order-validation",
    "project_name": "Order Validation Rules",
    "next_run": "2026-01-09T11:00:00Z",
    "cron_expression": "0 * * * *",
    "timezone": "UTC"
  }
]

curl http://localhost:8080/stats

Response:

{
  "total": 1250,
  "pending": 2,
  "running": 1,
  "success": 1180,
  "failed": 45,
  "cancelled": 12,
  "timeout": 10,
  "success_rate": 94.40
}

Cricket expects the following tables in the PostgreSQL database:

Generated detector projects automatically include:

Additional dependencies are detected from rule code imports.

docker build -t cricket-runner:latest .

docker run -d \
  --name cricket \
  -p 8080:8080 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/cricket \
  -e ENLIQ_REPORT_URL=https://api.enliq.io/v1/reports \
  cricket-runner:latest

version: '3.8'

services:
  cricket:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/cricket
      ENLIQ_REPORT_URL: https://api.enliq.io/v1/reports
      MAX_QUEUE_SIZE: 10
      EXECUTION_TIMEOUT: 600
    depends_on:
      - db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: cricket
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

loodos-arge-normx-cricket/
├── main.py                 # Application entry point
├── config.py               # Settings configuration
├── synthesizer.py          # Code generation engine
├── geppetto/
│   ├── api.py              # FastAPI monitoring endpoints
│   ├── executor.py         # Project execution logic
│   ├── scheduler.py        # Cron scheduling
│   ├── data/
│   │   └── models/
│   │       ├── data_source.py  # Data source configs
│   │       ├── execution.py    # Execution models
│   │       └── rule.py         # Discrepancy rules
│   └── db/
│       └── client.py       # PostgreSQL client
└── templates/
    └── child_app/          # Jinja2 templates for generated projects
        ├── main.py.j2
        ├── config.py.j2
        ├── pyproject.toml.j2
        └── logic/
            ├── detectors.py.j2
            └── processor.py.j2

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=geppetto

1. Add a new config model in geppetto/data/models/data_source.py
2. Update the union type DataSourceConfig
3. Add parsing logic in executor.py
4. Update templates in templates/child_app/

Proprietary - Loodos R&D

For issues and feature requests, contact the Loodos ARGE team.