Refactor codebase to enforce top-level imports, clean comments, remove inline ignores, and expand UI examples

analyzer.py

@@ -1,19 +1,16 @@
-"""
-Module responsible for orchestrating the overall journal entry analysis.
-Brings together inference, file extraction, response parsing, and heuristic fallbacks.
-"""
+# Module responsible for orchestrating the overall journal entry analysis.
+# Brings together inference, file extraction, response parsing, and fallback flows.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Any
 
-# Dynamic import fallback for ZeroGPU runtime environment compatibility
 try:
-    import spaces  # type: ignore
+    import spaces
 except ImportError:
-
+    # Dummy decorator used when spaces package is unavailable locally
     class _LocalSpacesFallback:
         @staticmethod
         def GPU(
@@ -27,7 +24,7 @@ except ImportError:
     spaces = _LocalSpacesFallback()
 
 from config import ENTRY_LIMIT, MODEL_ID, PARAMETER_COUNT
-from inference import run_model_inference, run_chat_inference
+from inference import run_chat_inference, run_model_inference
 from parser import extract_journal_text, parse_sections
 
 
@@ -125,6 +122,7 @@ def analyze_journal_ui(
 ) -> tuple[str, str, str, str, str, list[dict[str, str]], str]:
     """Gradio-compatible entry point decorated for Hugging Face ZeroGPU compatibility."""
     report = analyze_journal(file_path, raw_text)
+    # The last element returned updates the hidden journal_context state variable
     return (
         report.entry_text,
         report.model_path,
@@ -142,14 +140,7 @@ def chat_respond_ui(
     user_message: str,
     journal_context: str,
 ) -> tuple[list[dict[str, str]], str, str]:
-    """Gradio-compatible chat handler decorated for Hugging Face ZeroGPU compatibility.
-
-    Returns:
-        tuple containing:
-        - updated history list of dicts
-        - cleared user message textbox string ("")
-        - updated system logs string
-    """
+    """Gradio-compatible chat handler decorated for Hugging Face ZeroGPU compatibility."""
     updated_history = list(history) if history else []
     if not user_message.strip():
         return updated_history, "", "Empty user message. No inference run."

app.py

@@ -1,19 +1,19 @@
+# Entry point for the InnerSpace Gradio application.
+# Configures environment variables, patches warnings, and launches the interface.
+
 from __future__ import annotations
 
 import os
+from runtime import patch_asyncio_cleanup_warning
+from styles import CUSTOM_CSS
+from ui import create_app, get_theme
 
 # Disable Gradio Server-Side Rendering
 os.environ.setdefault("GRADIO_SSR_MODE", "false")
 
 # Patch asyncio to ignore minor event loop warnings on teardown
-from runtime import patch_asyncio_cleanup_warning  # noqa: E402
-
 patch_asyncio_cleanup_warning()
 
-# Import UI components and CSS styling
-from styles import CUSTOM_CSS  # noqa: E402
-from ui import create_app, get_theme  # noqa: E402
-
 # Build Gradio app block
 demo = create_app()
 theme = get_theme()

core.py

@@ -1,18 +1,8 @@
-"""
-InnerSpace Core API Facade.
-Provides a unified entry point for Gradio UI interactions.
-
-This file serves as a facade to maintain backward compatibility while delegating
-responsibilities to specialized modules according to SOLID principles:
-- `inference.py` handles model lazy-loading, caching, and inference.
-- `parser.py` handles file text extraction and output segment splitting.
-- `heuristics.py` handles keyword-based offline backup interpretations.
-- `analyzer.py` handles prompt formatting and orchestrates the pipeline.
-"""
+# InnerSpace Core API Facade.
+# Provides a unified entry point for Gradio UI interactions.
 
 from __future__ import annotations
 
-# Re-export key analytical components to maintain interface contracts
 from analyzer import (
     JournalReport,
     analyze_journal,

inference.py

@@ -1,17 +1,18 @@
-"""
-Module responsible for model loading and text generation.
-Handles local GPU/CPU execution and fallback to Hugging Face Serverless Inference API.
-"""
+# Module responsible for model loading and text generation.
+# Handles local GPU/CPU execution and fallback to Hugging Face Serverless Inference API.
 
 from __future__ import annotations
 
 import os
+import traceback
 from typing import Any
 import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from huggingface_hub import InferenceClient
 
 from config import MODEL_ID
 
-# Caches for the model and tokenizer to prevent re-loading on every call
+# Cache model and tokenizer to prevent reloading on subsequent runs
 _model: Any = None
 _tokenizer: Any = None
 
@@ -20,8 +21,6 @@ def get_model_and_tokenizer() -> tuple[Any, Any]:
     """Loads and caches the Hugging Face model and tokenizer lazily."""
     global _model, _tokenizer
     if _model is None:
-        from transformers import AutoModelForCausalLM, AutoTokenizer
-
         print(f"Loading tokenizer for {MODEL_ID}...")
         _tokenizer = AutoTokenizer.from_pretrained(
             MODEL_ID,
@@ -83,8 +82,6 @@ def run_model_inference(prompt: str) -> tuple[str, str]:
         return response, "\n".join(log_lines)
 
     except Exception as e:
-        import traceback
-
         traceback.print_exc()
         log_lines.append(
             f"Local model execution failed: {e}. Falling back to serverless API..."
@@ -95,8 +92,6 @@ def run_model_inference(prompt: str) -> tuple[str, str]:
         f"Initiating Hugging Face Serverless Inference API ({MODEL_ID})..."
     )
     try:
-        from huggingface_hub import InferenceClient
-
         client = InferenceClient(MODEL_ID, token=os.environ.get("HF_TOKEN"))
         messages = [{"role": "user", "content": prompt}]
         completion = client.chat_completion(messages=messages, max_tokens=512)
@@ -151,8 +146,6 @@ def run_chat_inference(
         return response, "\n".join(log_lines)
 
     except Exception as e:
-        import traceback
-
         traceback.print_exc()
         log_lines.append(
             f"Local chat execution failed: {e}. Falling back to serverless API..."
@@ -162,8 +155,6 @@ def run_chat_inference(
         f"Initiating Hugging Face Serverless Inference API for chat ({MODEL_ID})..."
     )
     try:
-        from huggingface_hub import InferenceClient
-
         client = InferenceClient(MODEL_ID, token=os.environ.get("HF_TOKEN"))
         messages = [{"role": "system", "content": system_prompt}] + history
         completion = client.chat_completion(messages=messages, max_tokens=256)

parser.py

@@ -1,7 +1,5 @@
-"""
-Module responsible for diary text file parsing and model output parsing.
-Extracts raw text from inputs and parses structured response blocks.
-"""
+# Module responsible for diary text file parsing and model output parsing.
+# Extracts raw text from inputs and parses structured response blocks.
 
 from __future__ import annotations
 

pyrightconfig.json

@@ -0,0 +1,3 @@
+{
+  "reportMissingImports": "none"
+}

runtime.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import os
+from pathlib import Path
 import asyncio.base_events as base_events
 from typing import Any
 
@@ -7,7 +9,7 @@ from typing import Any
 def patch_asyncio_cleanup_warning() -> None:
     """Patches asyncio EventLoop __del__ method to ignore harmless file descriptor cleanup warnings in notebook/interactive runs."""
     original_del = getattr(base_events.BaseEventLoop, "__del__", None)
-    if original_del is None or getattr(original_del, "_neighbordocs_patched", False):
+    if original_del is None or getattr(original_del, "_innerspace_patched", False):
         return
 
     def patched_del(self: Any) -> None:
@@ -17,15 +19,12 @@ def patch_asyncio_cleanup_warning() -> None:
             if str(exc) != "Invalid file descriptor: -1":
                 raise
 
-    patched_del._neighbordocs_patched = True  # type: ignore[attr-defined]
-    base_events.BaseEventLoop.__del__ = patched_del  # type: ignore[method-assign]
+    setattr(patched_del, "_innerspace_patched", True)
+    setattr(base_events.BaseEventLoop, "__del__", patched_del)
 
 
 def load_env() -> None:
     """Loads environment variables from .env if present in the current or parent directory."""
-    import os
-    from pathlib import Path
-
     for path in [Path(".env"), Path("../.env")]:
         if path.is_file():
             try:
@@ -35,7 +34,8 @@ def load_env() -> None:
                         if line and not line.startswith("#") and "=" in line:
                             k, v = line.split("=", 1)
                             os.environ.setdefault(k.strip(), v.strip().strip("'\""))
-                break  # Stop after loading the first found .env file
+                # Stop after loading the first found .env file
+                break
             except Exception:
                 pass
 

tune_journal.py

@@ -1,7 +1,21 @@
 from __future__ import annotations
 
 import os
-import modal  # type: ignore
+import torch
+import modal
+from datasets import Dataset
+from peft import (
+    LoraConfig,
+    get_peft_model,
+    prepare_model_for_kbit_training,
+)
+from transformers import (
+    AutoModelForCausalLM,
+    AutoTokenizer,
+    BitsAndBytesConfig,
+    TrainingArguments,
+)
+from trl import SFTTrainer
 
 # Define the Modal App
 app = modal.App("inner-space-tuner")
@@ -24,35 +38,21 @@ volume = modal.Volume.from_name("inner-space-checkpoints", create_if_missing=Tru
 MODEL_ID = "openbmb/MiniCPM5-1B-SFT"
 
 
+# Targets single A10G GPU for cost-effective execution
+# Two hours timeout
 @app.function(
     image=image,
-    gpu="A10G",  # Targets single A10G GPU for cost-effective execution
-    timeout=7200,  # 2 hours timeout
+    gpu="A10G",
+    timeout=7200,
     volumes={"/checkpoints": volume},
 )
 def train_lora(hf_token: str | None = None, repo_id: str | None = None):
     """Fine-tunes openbmb/MiniCPM5-1B-SFT on cognitive behavioral reflections using QLoRA."""
-    import torch
-    from datasets import Dataset  # type: ignore
-    from peft import (  # type: ignore
-        LoraConfig,
-        get_peft_model,
-        prepare_model_for_kbit_training,
-    )
-    from transformers import (
-        AutoModelForCausalLM,
-        AutoTokenizer,
-        BitsAndBytesConfig,
-        TrainingArguments,
-    )
-    from trl import SFTTrainer  # type: ignore
-
     print(f"Loading tokenizer for {MODEL_ID}...")
     tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
     tokenizer.pad_token = tokenizer.eos_token
 
-    # Step 1: Prepare a synthetic CBT/Mindfulness journal dataset
-    # In a real-world scenario, you would load this from Hugging Face Hub (e.g., load_dataset("CBT-Reflections"))
+    # Prepare a synthetic CBT/Mindfulness journal dataset
     print("Preparing training dataset...")
     raw_data = [
         {
@@ -108,7 +108,7 @@ def train_lora(hf_token: str | None = None, repo_id: str | None = None):
 
     dataset = Dataset.from_list(formatted_dataset)
 
-    # Step 2: Configure 4-bit QLoRA quantization for resource efficiency
+    # Configure 4-bit QLoRA quantization for resource efficiency
     print("Configuring QLoRA...")
     bnb_config = BitsAndBytesConfig(
         load_in_4bit=True,
@@ -128,7 +128,7 @@ def train_lora(hf_token: str | None = None, repo_id: str | None = None):
     # Prepare model for PEFT training
     model = prepare_model_for_kbit_training(model)
 
-    # Step 3: Configure LoRA Adapter
+    # Configure LoRA Adapter
     peft_config = LoraConfig(
         r=8,
         lora_alpha=16,
@@ -140,7 +140,7 @@ def train_lora(hf_token: str | None = None, repo_id: str | None = None):
     model = get_peft_model(model, peft_config)
     model.print_trainable_parameters()
 
-    # Step 4: Configure Training Arguments
+    # Configure Training Arguments
     training_args = TrainingArguments(
         output_dir="/checkpoints/inner-space-lora",
         per_device_train_batch_size=1,
@@ -157,7 +157,7 @@ def train_lora(hf_token: str | None = None, repo_id: str | None = None):
         report_to="none",
     )
 
-    # Step 5: Start Training
+    # Start Training
     print("Starting fine-tuning job on Modal...")
     trainer = SFTTrainer(
         model=model,
@@ -169,7 +169,7 @@ def train_lora(hf_token: str | None = None, repo_id: str | None = None):
     trainer.train()
     print("Fine-tuning completed successfully!")
 
-    # Step 6: Save and push adapter to Hugging Face Hub (optional)
+    # Save and push adapter to Hugging Face Hub
     print("Saving fine-tuned adapter...")
     model.save_pretrained("/checkpoints/inner-space-final")
     tokenizer.save_pretrained("/checkpoints/inner-space-final")

ui.py

@@ -1,7 +1,11 @@
+# Module responsible for creating and laying out the Gradio interface.
+# Connects UI input components to core logical workflows.
+
 from __future__ import annotations
 
-import gradio as gr
 from typing import Any
+import gradio as gr
+from gradio.themes import Soft
 
 from config import (
     APP_DESCRIPTION,
@@ -14,7 +18,7 @@ from core import analyze_journal_ui, chat_respond_ui
 
 def get_theme() -> Any:
     """Returns the custom soft theme configured for dark slate violet styling."""
-    theme = gr.themes.Soft(  # type: ignore
+    theme = Soft(
         primary_hue="violet",
         secondary_hue="slate",
         neutral_hue="slate",
@@ -114,7 +118,7 @@ def create_app() -> gr.Blocks:
                 elem_classes=["nd-log-box"],
             )
 
-        # Demo examples for one-click test runs
+        # Preloaded examples for one-click test runs
         gr.Examples(
             examples=[
                 [
@@ -123,7 +127,23 @@ def create_app() -> gr.Blocks:
                 ],
                 [
                     None,
-                    "Had an amazing weekend! Met up with an old high school friend. We talked for hours over coffee and reminsiced. I felt so connected and energized. Need to remember to reach out to people more often.",
+                    "I've been working 12-hour days all week. I feel completely exhausted, but if I take a break, my team will fall behind and it'll be my fault. I just need to push through, but I can barely think straight.",
+                ],
+                [
+                    None,
+                    "I got promoted to senior engineer, but I'm terrified. I only got it because they like me, not because I'm actually good at this. Soon they'll assign me a complex task, I'll fail, and everyone will realize I'm a fraud.",
+                ],
+                [
+                    None,
+                    "My best friend forgot my birthday. They didn't even text me. I thought we were close, but clearly they don't value our friendship as much as I do. I should just stop talking to them entirely.",
+                ],
+                [
+                    None,
+                    "I've had a headache for two days. I googled it and it says it could be a brain tumor. I'm terrified. I can't focus on anything else and I feel like my life is ending.",
+                ],
+                [
+                    None,
+                    "Had an amazing weekend! Met up with an old high school friend. We talked for hours over coffee and reminisced. I felt so connected and energized.",
                 ],
             ],
             inputs=[file_input, notes_input],