Where Are the Utility Functions in DeepTutor Defined?

All utility functions in DeepTutor are centralized in the deeptutor/utils package, which houses six specialized modules for JSON parsing, network resilience, error handling, document validation, and runtime configuration management.

The HKUDS/DeepTutor repository organizes its reusable helper code under a dedicated utilities package to maintain clean separation of concerns across the AI tutoring system. Understanding where these utility functions in DeepTutor reside and how to invoke them is essential for extending the platform or debugging provider interactions. All common-purpose utilities are implemented as plain Python modules under the deeptutor/utils directory, covering everything from LLM response parsing to file upload safety.

Location of Utility Functions in DeepTutor

The deeptutor/utils directory serves as the single source of truth for shared functionality. When you need to handle malformed JSON from an LLM, throttle failing external providers, or validate user uploads, you import from this package. The modules are imported throughout the codebase wherever a shared capability is needed, ensuring consistent behavior across the application.

Core Utility Modules in DeepTutor

JSON Parsing and Repair

The deeptutor/utils/json_parser.py module provides safe extraction of JSON from LLM responses, including automatic fixing of malformed payloads. The primary function, parse_json_response, handles markdown-wrapped JSON blocks and syntax errors gracefully.

# Example: parsing LLM JSON response safely

from deeptutor.utils.json_parser import parse_json_response

raw = "```json\n{ 'answer': 42 }\n```"
data = parse_json_response(raw)          # → {'answer': 42}

Network Circuit Breaker

Located at deeptutor/utils/network/circuit_breaker.py, this module protects external providers by opening or closing the circuit based on recent failure rates. The functions is_call_allowed, record_call_success, and record_call_failure work in tandem with the error rate tracker to prevent cascading failures when calling LLM APIs or document processors.

# Example: protecting a provider call with the circuit breaker

from deeptutor.utils.network.circuit_breaker import is_call_allowed, record_call_success, record_call_failure

provider = "openai"
if is_call_allowed(provider):
    try:
        result = external_api_call()
        record_call_success(provider)
    except Exception:
        record_call_failure(provider)
        raise

Error Formatting

The deeptutor/utils/error_utils.py module extracts useful information from exceptions, especially JSON-encoded API errors, and presents clean, actionable messages. Use format_exception_message to convert raw exceptions into user-friendly strings for logging or UI display.

# Example: formatting an exception from a remote API

from deeptutor.utils.error_utils import format_exception_message

try:
    risky_operation()
except Exception as exc:
    friendly_msg = format_exception_message(exc)
    logger.error(f"Operation failed: {friendly_msg}")

Error-Rate Tracking

The deeptutor/utils/error_rate_tracker.py module maintains sliding-window statistics per provider with optional alert callbacks. Used internally by the circuit breaker, it tracks failure rates over time to determine when a provider should be temporarily blacklisted.

Document Validation

The deeptutor/utils/document_validator.py module performs sanity checks on uploaded files, validating size limits, extensions, MIME types, and safe filenames. The DocumentValidator.validate_file method returns structured metadata about the file after security checks.

# Example: validating an uploaded document before processing

from deeptutor.utils.document_validator import DocumentValidator

info = DocumentValidator.validate_file("/tmp/user_upload/myfile.pdf")

# `info` now contains safe filename, size, extension, etc.

Runtime Configuration Management

The deeptutor/utils/config_manager.py module provides a lightweight YAML loader and saver for user-level settings. The ConfigManager class handles persistence and retrieval of application preferences without requiring database access.

# Example: loading a user‑level setting

from deeptutor.utils.config_manager import ConfigManager

cfg = ConfigManager().load_config()
model = cfg.get("model", "gpt-4")

Summary

• All utility functions in DeepTutor live in the deeptutor/utils package according to the source code structure.
• json_parser.py handles safe LLM response parsing with automatic repair of malformed JSON.
• circuit_breaker.py and error_rate_tracker.py manage provider resilience and prevent cascading failures.
• error_utils.py formats exceptions cleanly, especially for JSON-encoded API errors.
• document_validator.py secures file uploads through multi-layer validation.
• config_manager.py manages YAML configuration persistence for user settings.

Frequently Asked Questions

Where are DeepTutor utility functions located?

They are centralized in the deeptutor/utils directory. This package contains six specialized modules covering JSON parsing, network protection via circuit breakers, error handling, file validation, and configuration management.

How does DeepTutor parse JSON from LLM responses?

DeepTutor uses the parse_json_response function from deeptutor/utils/json_parser.py to safely extract and repair JSON content. This function handles markdown code blocks, single quotes, and other common LLM output malformations automatically.

What is the circuit breaker pattern used for in DeepTutor?

The circuit breaker in deeptutor/utils/network/circuit_breaker.py prevents cascading failures by temporarily blocking calls to failing external providers when error rates exceed thresholds. It uses the error rate tracker to monitor sliding-window statistics and automatically resumes allowing calls after the failure rate drops.

How does DeepTutor validate uploaded documents?

Uploaded files are validated through deeptutor/utils/document_validator.py, which checks file sizes, extensions, MIME types, and filename safety via the DocumentValidator.validate_file method before any processing occurs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}