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.