nlproxy/docs/utils.md

# NLProxy Utilities Module Reference

This document covers shared utility modules in `utils/`.

## Purpose

Utility modules centralize constants, pricing data, and logging configuration used across the NLProxy codebase.

## Files

### `utils/constants.py`

#### Purpose

Provides canonical pricing data, aggressiveness presets, semantic firewall defaults, and other system constants.

#### Pricing

- `MODEL_PRICING` contains per-1,000-token pricing for supported models.
- Pricing can be overridden using environment variables of the form:
  - `NLPROXY_PRICE_{MODEL_NAME}_INPUT`
  - `NLPROXY_PRICE_{MODEL_NAME}_OUTPUT`
- `_normalize_pricing_env_name()` sanitizes the model name into a valid env var segment.
- `PROVIDER_PRICING` is the runtime pricing table after env overrides.

#### Aggressiveness Presets

- `AGGRESSIVENESS_MAP`
  - `legal`: `0.25`
  - `finance`: `0.30`
  - `code`: `0.45`
  - `general`: `0.40`

#### Semantic Firewall Defaults

- `SEMANTIC_FIREWALL_CONFIG` controls optional semantic attack detection.
- Default device preference is `cpu`.
- Similarity threshold is `0.85` by default.

#### Semantic Stopwords

- `SEMANTIC_STOPWORDS` contains curated low-value phrases used during prompt reconstruction.
- Includes English and Spanish tokens for bilingual prompt handling.

#### System Defaults

- `DEFAULT_AGGRESSIVENESS`: `0.2`
- `DEFAULT_CONFIDENCE_THRESHOLD`: `0.6`
- `DEFAULT_MAX_TOKENS`: `512`
- `DEFAULT_TIMEOUT_SECONDS`: `30.0`
- `DEFAULT_BATCH_SIZE`: `32`
- `DEFAULT_EMBEDDING_DIM`: `384`
- `DEFAULT_SIMILARITY_THRESHOLD`: `0.92`

#### API Constants

- `API_VERSION`: `v1`
- `CHAT_ENDPOINT`: `/v1/chat/completions`
- `HEALTH_ENDPOINT`: `/health`
- `METRICS_ENDPOINT`: `/metrics`
- `DOCS_ENDPOINT`: `/docs`

#### Security Constants

- `PLACEHOLDER_PREFIX`: `__PROT_`
- `MAX_PROMPT_LENGTH`: `100_000`
- `MAX_RESPONSE_LENGTH`: `50_000`
- `ALLOWED_ROLES`: `{"system", "user", "assistant"}`

#### Utility Functions

- `get_pricing(model_name: str) -> Dict[str, float]`
  - Returns pricing data for a given model name.
  - Falls back to `default` pricing if unknown.

### `utils/logger.py`

#### Purpose

Standardizes logging configuration and request-context logging across the project.

#### Key Components

- `ContextFilter`
  - Thread-local context propagation for `request_id`, `user_id`, and custom fields.
  - Methods: `set_context()`, `get_context()`, `clear_context()`.

- `JSONFormatter`
  - Emits structured JSON logs for production observability.
  - Includes timestamp, level, module, function, line, and additional context.

- `PrettyFormatter`
  - Emits ANSI-colored human-readable logs for development.

- `setup_logging(level, format_type, log_dir, max_bytes, backup_count, disable_existing)`
  - Configures root logger and optional rotating file output.
  - Detects environment via `NLPROXY_ENV`.

- `get_request_logger(name)`
  - Returns a `LoggerAdapter` bound to current context.

#### Performance Considerations

- Logging format is selected based on environment to balance readability and parsing.
- File rotation prevents unbounded disk growth.
- Third-party noise is suppressed for stable runtime logs.

#### Edge Cases

- `setup_logging()` is idempotent and no-op after first initialization.
- Context filter gracefully handles missing context data.

## Implementation Notes

- Utility modules are intentionally low-dependency and safe to import in startup initialization.
- Logging format selection is automatic unless overridden explicitly.