# common

> Common guidelines and utilities for the QUVI Engine project.

- Author: sttking
- Repository: sttking/educate_page
- Version: 20260130165115
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/sttking/educate_page
- Web: https://mule.run/skillshub/@@sttking/educate_page~common:20260130165115

---

---
name: common
description: Common guidelines and utilities for the QUVI Engine project.
---

# QUVI Engine Common Skills

This document covers common operations and guidelines applicable across all modules.

## Server Management

### Starting the Server

Use `run.sh` to start both v2 and v3 server instances:

```bash
./run.sh
```

This starts:
- **v2 API** on port `8098` (or `$PORT_V2`)
- **v3 API** on port `8099` (or `$PORT_V3`)

Logs are written to:
- `logs/engine_v2.log`
- `logs/engine_v3.log`

### Stopping the Server

Use `stop.sh` to gracefully stop all running instances:

```bash
./stop.sh
```

This will:
1. Find processes listening on ports 8098 and 8099
2. Send graceful shutdown signal (SIGTERM)
3. Force kill (SIGKILL) if process doesn't stop within 5 seconds

### Restarting the Server

To restart after code changes:

```bash
./stop.sh && ./run.sh
```

Or to check logs after restart:

```bash
./stop.sh && ./run.sh && sleep 2 && tail -f logs/engine_v3.log
```

## Critical Rules

### 1. Vendor Setup for SQLGlot

**Important**: When using `sqlglot` anywhere in this project, you **MUST** import `vendor_setup` at the very top of the file, before any other imports.

```python
import vendor_setup  # MUST be the first import
from sqlglot import exp, parse_one
...
```

This ensures the custom vendored version of `sqlglot` is loaded correctly.

### 2. Logging Convention

Use the project's logger setup pattern:

```python
from utils.logger import setup_logger

logger = setup_logger("module_name")

# Use emoji prefixes for log categories
logger.info("✅ Operation succeeded")
logger.warning("⚠️ Warning message")
logger.error("❌ Error occurred")
logger.debug("🔍 Debug info")
```

### 3. DTO Pattern

For data exchange, use Pydantic models in `dto/` or dataclasses with `from_dict`/`to_dict`:

```python
from dataclasses import dataclass, asdict
from typing import Dict, Any

@dataclass
class MyType:
    field1: str
    field2: int

    def to_dict(self) -> Dict[str, Any]:
        return asdict(self)

    @staticmethod
    def from_dict(d: Dict[str, Any]) -> "MyType":
        return MyType(
            field1=d.get("field1", ""),
            field2=d.get("field2", 0)
        )
```

### 4. Error Handling

- Prefer graceful degradation over throwing exceptions
- Return low confidence scores instead of crashing
- Log warnings but continue processing when possible

## Testing

### Running Tests

Test scripts are located in `test/` directory:

```bash
# Run all tests
./test/test_all.sh

# Run specific module tests
./test/query/predict_time/predict_time_test.sh http://localhost:8099

# Run semantic tests
./test/semantic/smq2sql_test.sh
```

### Test Conventions

- Use bash scripts for integration tests
- Scripts should be self-contained and executable
- Use colored output for pass/fail indication
- Return exit code 0 for success, non-zero for failure

## Module-Specific Skills

For detailed guidelines on specific modules, see:

- **[Query Predictor](query_predictor/SKILL.md)**: SQL execution time prediction
- **[Semantic Engine](semantic_engine/SKILL.md)**: SMQ ↔ SQL transformation