DeepFabric 4.4.0__py3-none-any.whl

deepfabric/topic_manager.py

@@ -0,0 +1,303 @@
+import asyncio
+import traceback
+
+from typing import TYPE_CHECKING
+
+from .config import DeepFabricConfig
+from .constants import (
+    TOPIC_TREE_DEFAULT_DEGREE,
+    TOPIC_TREE_DEFAULT_DEPTH,
+    TOPIC_TREE_DEFAULT_TEMPERATURE,
+)
+from .exceptions import ConfigurationError
+from .factory import create_topic_generator
+from .graph import Graph
+from .topic_model import TopicModel
+from .tree import Tree
+from .tui import get_graph_tui, get_tree_tui, get_tui
+from .utils import read_topic_tree_from_jsonl
+
+if TYPE_CHECKING:
+    from .topic_model import TopicModel
+
+
+def _ensure_not_running_loop(func_name: str) -> None:
+    """Raise a helpful error if invoked from an active asyncio loop."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+
+    if loop.is_running():
+        msg = (
+            f"{func_name} cannot be called from within an active event loop. "
+            f"Use `{func_name}_async` instead."
+        )
+        raise RuntimeError(msg)
+
+
+async def _process_graph_events(graph: Graph, debug: bool = False) -> dict | None:
+    from .progress import ProgressReporter  # noqa: PLC0415
+
+    tui = get_graph_tui()
+
+    # Create and attach progress reporter for streaming
+    progress_reporter = ProgressReporter()
+    progress_reporter.attach(tui)
+    graph.progress_reporter = progress_reporter
+
+    tui_started = False
+
+    final_event = None
+    try:
+        async for event in graph.build_async():
+            if event["event"] == "depth_start":
+                if not tui_started:
+                    tui.start_building(
+                        graph.model_name, graph.depth, graph.degree, graph.topic_prompt
+                    )
+                    tui_started = True
+                depth = int(event["depth"]) if isinstance(event["depth"], str | int) else 0
+                leaf_count = (
+                    int(event.get("leaf_count", 0))
+                    if isinstance(event.get("leaf_count", 0), str | int)
+                    else 0
+                )
+                tui.start_depth_level(depth, leaf_count)
+            elif event["event"] == "node_expanded":
+                subtopics_added = (
+                    int(event["subtopics_added"])
+                    if isinstance(event["subtopics_added"], str | int)
+                    else 0
+                )
+                connections_added = (
+                    int(event.get("connections_added", 0))
+                    if isinstance(event.get("connections_added", 0), str | int)
+                    else 0
+                )
+                tui.complete_node_expansion(event["node_topic"], subtopics_added, connections_added)
+            elif event["event"] == "depth_complete":
+                depth = int(event["depth"]) if isinstance(event["depth"], str | int) else 0
+                tui.complete_depth_level(depth)
+            elif event["event"] == "build_complete":
+                failed_generations = (
+                    int(event.get("failed_generations", 0))
+                    if isinstance(event.get("failed_generations", 0), str | int)
+                    else 0
+                )
+                tui.finish_building(failed_generations)
+                final_event = event
+
+                if debug and failed_generations > 0 and hasattr(graph, "failed_generations"):
+                    get_tui().error("\nDebug: Graph generation failures:")
+                    for idx, failure in enumerate(graph.failed_generations, 1):
+                        node_id = failure.get("node_id", "unknown")
+                        attempts = failure.get("attempts", 0)
+                        last_error = failure.get("last_error", "Unknown error")
+                        get_tui().error(f"  [{idx}] Node ID: {node_id}, Attempts: {attempts}")
+                        get_tui().error(f"      Error: {last_error}")
+    except Exception as e:
+        if debug:
+            get_tui().error(f"Debug: Full traceback:\n{traceback.format_exc()}")
+        get_tui().error(f"Graph build failed: {str(e)}")
+        raise
+    else:
+        return final_event
+
+
+async def _process_tree_events(tree: Tree, debug: bool = False) -> dict | None:
+    from .progress import ProgressReporter  # noqa: PLC0415
+
+    tui = get_tree_tui()
+
+    # Create and attach progress reporter for streaming
+    progress_reporter = ProgressReporter()
+    progress_reporter.attach(tui)
+    tree.progress_reporter = progress_reporter
+
+    final_event = None
+    try:
+        async for event in tree.build_async():
+            if event["event"] == "build_start":
+                depth = int(event["depth"]) if isinstance(event["depth"], str | int) else 0
+                degree = int(event["degree"]) if isinstance(event["degree"], str | int) else 0
+                tui.start_building(event["model_name"], depth, degree, tree.topic_prompt)
+            elif event["event"] == "subtopics_generated":
+                if not event["success"]:
+                    tui.add_failure()
+                    if debug and "error" in event:
+                        get_tui().error(f"Debug: Tree generation failure - {event['error']}")
+            elif event["event"] == "build_complete":
+                total_paths = (
+                    int(event["total_paths"]) if isinstance(event["total_paths"], str | int) else 0
+                )
+                failed_generations = (
+                    int(event["failed_generations"])
+                    if isinstance(event["failed_generations"], str | int)
+                    else 0
+                )
+                tui.finish_building(total_paths, failed_generations)
+                final_event = event
+
+                if debug and failed_generations > 0 and hasattr(tree, "failed_generations"):
+                    get_tui().error("\nDebug: Tree generation failures:")
+                    for idx, failure in enumerate(tree.failed_generations, 1):
+                        get_tui().error(
+                            f"  [{idx}] Path: {' -> '.join(failure.get('node_path', []))}"
+                        )
+                        get_tui().error(f"      Error: {failure.get('error', 'Unknown error')}")
+    except Exception as e:
+        if debug:
+            get_tui().error(f"Debug: Full traceback:\n{traceback.format_exc()}")
+        get_tui().error(f"Tree build failed: {str(e)}")
+        raise
+    else:
+        return final_event
+
+
+def handle_graph_events(graph: Graph, debug: bool = False) -> dict | None:
+    """
+    Build graph with TUI progress.
+
+    Args:
+        graph: Graph object to build
+        debug: Enable debug output
+
+    Returns:
+        Final build event dictionary or None
+
+    Raises:
+        Exception: If graph build fails
+    """
+    _ensure_not_running_loop("handle_graph_events")
+    return asyncio.run(_process_graph_events(graph, debug=debug))
+
+
+async def handle_graph_events_async(graph: Graph, debug: bool = False) -> dict | None:
+    return await _process_graph_events(graph, debug=debug)
+
+
+def handle_tree_events(tree: Tree, debug: bool = False) -> dict | None:
+    """
+    Build tree with TUI progress.
+
+    Args:
+        tree: Tree object to build
+        debug: Enable debug output
+
+    Returns:
+        Final build event dictionary or None
+
+    Raises:
+        Exception: If tree build fails
+    """
+    _ensure_not_running_loop("handle_tree_events")
+    return asyncio.run(_process_tree_events(tree, debug=debug))
+
+
+async def handle_tree_events_async(tree: Tree, debug: bool = False) -> dict | None:
+    return await _process_tree_events(tree, debug=debug)
+
+
+def load_or_build_topic_model(
+    config: DeepFabricConfig,
+    topics_load: str | None = None,
+    topics_overrides: dict | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    base_url: str | None = None,
+    debug: bool = False,
+) -> TopicModel:
+    """
+    Load topic model from file or build new one.
+
+    Args:
+        config: DeepFabricConfig object
+        topics_load: Path to existing topics file (JSONL for tree, JSON for graph)
+        topics_overrides: Override parameters for topic generation
+        provider: LLM provider
+        model: Model name
+        base_url: Base URL for LLM API
+        debug: Enable debug output
+
+    Returns:
+        TopicModel (Tree or Graph)
+
+    Raises:
+        ConfigurationError: If loading or building fails
+    """
+    tui = get_tui()
+
+    if topics_load:
+        # Determine mode from config or file extension
+        is_graph = config.topics.mode == "graph" or topics_load.endswith(".json")
+
+        if is_graph:
+            tui.info(f"Reading topic graph from JSON file: {topics_load}")
+            topics_params = config.get_topics_params(**(topics_overrides or {}))
+            return Graph.from_json(topics_load, topics_params)
+        tui.info(f"Reading topic tree from JSONL file: {topics_load}")
+        dict_list = read_topic_tree_from_jsonl(topics_load)
+
+        final_provider = provider or "ollama"
+        final_model = model or "mistral:latest"
+
+        topic_model = Tree(
+            topic_prompt="default",
+            provider=final_provider,
+            model_name=final_model,
+            topic_system_prompt="",
+            degree=TOPIC_TREE_DEFAULT_DEGREE,
+            depth=TOPIC_TREE_DEFAULT_DEPTH,
+            temperature=TOPIC_TREE_DEFAULT_TEMPERATURE,
+            base_url=base_url,
+        )
+        topic_model.from_dict_list(dict_list)
+        return topic_model
+
+    # Build new topic model
+    topic_model = create_topic_generator(config, topics_overrides=topics_overrides)
+
+    # Build with appropriate event handler
+    if isinstance(topic_model, Graph):
+        handle_graph_events(topic_model, debug=debug)
+    elif isinstance(topic_model, Tree):
+        handle_tree_events(topic_model, debug=debug)
+
+    return topic_model
+
+
+def save_topic_model(
+    topic_model: TopicModel,
+    config: DeepFabricConfig,
+    topics_save_as: str | None = None,
+) -> None:
+    """
+    Save topic model to file.
+
+    Args:
+        topic_model: TopicModel to save (Tree or Graph)
+        config: DeepFabricConfig object
+        topics_save_as: Override path for saving topics
+
+    Raises:
+        ConfigurationError: If saving fails
+    """
+    tui = get_tui()
+
+    if isinstance(topic_model, Tree):
+        try:
+            tree_save_path = topics_save_as or config.topics.save_as or "topic_tree.jsonl"
+            topic_model.save(tree_save_path)
+            tui.success(f"Topic tree saved to {tree_save_path}")
+            tui.info(f"Total paths: {len(topic_model.tree_paths)}")
+        except Exception as e:
+            raise ConfigurationError(f"Error saving topic tree: {str(e)}") from e
+
+    elif isinstance(topic_model, Graph):
+        try:
+            graph_save_path = topics_save_as or config.topics.save_as or "topic_graph.json"
+            topic_model.save(graph_save_path)
+            tui.success(f"Topic graph saved to {graph_save_path}")
+        except Exception as e:
+            raise ConfigurationError(f"Error saving topic graph: {str(e)}") from e

deepfabric/topic_model.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+
+
+class TopicModel(ABC):
+    """Abstract base class for topic models like Tree and Graph."""
+
+    @abstractmethod
+    async def build_async(self) -> None:
+        """Asynchronously build the topic model."""
+        raise NotImplementedError
+
+    def build(self) -> None:  # pragma: no cover - legacy compatibility
+        """Deprecated synchronous entry point kept for legacy compatibility."""
+        msg = "TopicModel.build() is no longer supported. Use build_async() instead."
+        raise RuntimeError(msg)
+
+    @abstractmethod
+    def get_all_paths(self) -> list[list[str]]:
+        """Returns all the paths in the topic model."""
+        raise NotImplementedError

deepfabric/training/__init__.py

@@ -0,0 +1,35 @@
+"""DeepFabric training metrics logging.
+
+This module provides integration with HuggingFace Trainer and TRL trainers
+to log training metrics to the DeepFabric SaaS backend.
+
+Features:
+- Non-blocking async metrics sending
+- Notebook-friendly API key prompts (like wandb)
+- Graceful handling of failures without impacting training
+
+Usage:
+    from deepfabric.training import DeepFabricCallback
+
+    trainer = Trainer(
+        model=model,
+        args=training_args,
+        train_dataset=train_dataset,
+    )
+    trainer.add_callback(DeepFabricCallback(trainer))
+    trainer.train()
+
+Environment Variables:
+    DEEPFABRIC_API_KEY: API key for authentication
+    DEEPFABRIC_API_URL: SaaS backend URL (default: https://api.deepfabric.ai)
+"""
+
+from __future__ import annotations
+
+from .callback import DeepFabricCallback
+from .metrics_sender import MetricsSender
+
+__all__ = [
+    "DeepFabricCallback",
+    "MetricsSender",
+]

deepfabric/training/api_key_prompt.py

@@ -0,0 +1,302 @@
+"""API key prompt for notebooks and terminals."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+
+logger = logging.getLogger(__name__)
+
+# Cache for API key to avoid repeated prompts
+_api_key_cache: str | None = None
+_api_key_checked: bool = False
+
+
+def _is_notebook() -> bool:
+    """Check if running in Jupyter/Colab notebook."""
+    try:
+        from IPython import get_ipython  # type: ignore # noqa: PLC0415
+
+        shell = get_ipython()
+        if shell is None:
+            is_nb = False
+        else:
+            shell_name = shell.__class__.__name__
+            # ZMQInteractiveShell = Jupyter, Shell = Colab
+            is_nb = shell_name in ("ZMQInteractiveShell", "Shell", "Google Colab")
+    except (NameError, AttributeError, ImportError):
+        return False
+    else:
+        return is_nb
+
+
+def _is_colab() -> bool:
+    """Check if running in Google Colab specifically."""
+    try:
+        import google.colab  # type: ignore # noqa: F401, PLC0415
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+def _is_interactive_terminal() -> bool:
+    """Check if running in interactive terminal."""
+    try:
+        return sys.stdin is not None and sys.stdin.isatty()
+    except Exception:
+        return False
+
+
+def _show_notebook_prompt() -> str | None:
+    """Show inline widget in Jupyter/Colab (like wandb).
+
+    Returns:
+        API key string or None if skipped
+    """
+    try:
+        import ipywidgets as widgets  # type: ignore # noqa: PLC0415
+
+        from IPython.display import HTML, display  # type: ignore # noqa: PLC0415
+    except ImportError:
+        logger.debug("ipywidgets not available, falling back to terminal prompt")
+        return None
+
+    # Result container for callback
+    result = {"key": None, "submitted": False}
+
+    # Create styled input widget
+    api_key_input = widgets.Password(
+        placeholder="Enter your DeepFabric API key",
+        description="",
+        layout=widgets.Layout(width="300px"),
+        style={"description_width": "0px"},
+    )
+
+    submit_button = widgets.Button(
+        description="Submit",
+        button_style="primary",
+        layout=widgets.Layout(width="80px"),
+    )
+
+    skip_button = widgets.Button(
+        description="Skip",
+        button_style="",
+        layout=widgets.Layout(width="80px"),
+        tooltip="Disable logging for this session",
+    )
+
+    status_output = widgets.Output()
+
+    def on_submit(_button):  # noqa: ARG001
+        key = api_key_input.value.strip()
+        if key:
+            result["key"] = key
+            result["submitted"] = True
+            with status_output:
+                status_output.clear_output()
+                print("API key set. Training metrics will be logged to DeepFabric.")
+        else:
+            with status_output:
+                status_output.clear_output()
+                print("Please enter a valid API key.")
+
+    def on_skip(_button):  # noqa: ARG001
+        result["key"] = None
+        result["submitted"] = True
+        with status_output:
+            status_output.clear_output()
+            print("Logging disabled for this session.")
+
+    submit_button.on_click(on_submit)
+    skip_button.on_click(on_skip)
+
+    # Display styled header
+    display(
+        HTML(
+            """
+        <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                    border-radius: 8px; padding: 16px; margin: 8px 0; color: white;">
+            <div style="display: flex; align-items: center; margin-bottom: 8px;">
+                <svg width="24" height="24" viewBox="0 0 24 24" fill="white" style="margin-right: 8px;">
+                    <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/>
+                </svg>
+                <span style="font-size: 18px; font-weight: 600;">DeepFabric Training Metrics</span>
+            </div>
+            <p style="margin: 0; font-size: 14px; opacity: 0.9;">
+                Enter your API key to automatically log training metrics.<br>
+                Get your key at <a href="https://app.deepfabric.ai/settings/api"
+                   target="_blank" style="color: #fff; text-decoration: underline;">
+                   app.deepfabric.ai/settings/api</a>
+            </p>
+        </div>
+    """
+        )
+    )
+
+    # Display input widgets
+    input_box = widgets.HBox(
+        [api_key_input, submit_button, skip_button],
+        layout=widgets.Layout(margin="8px 0"),
+    )
+    display(input_box)
+    display(status_output)
+
+    # Wait for user input (with timeout)
+    timeout = 300  # 5 minutes
+    start = time.monotonic()
+
+    while not result["submitted"] and (time.monotonic() - start) < timeout:
+        time.sleep(0.1)
+
+    if not result["submitted"]:
+        # Timeout - treat as skip
+        with status_output:
+            status_output.clear_output()
+            print("Prompt timed out. Logging disabled for this session.")
+        return None
+
+    return result["key"]
+
+
+def _show_colab_prompt() -> str | None:
+    """Show Colab-specific prompt using getpass.
+
+    Returns:
+        API key string or None if skipped
+    """
+    try:
+        from getpass import getpass  # noqa: PLC0415
+
+        from IPython.display import HTML, display  # type: ignore # noqa: PLC0415
+
+        display(
+            HTML(
+                """
+            <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                        border-radius: 8px; padding: 16px; margin: 8px 0; color: white;">
+                <div style="font-size: 18px; font-weight: 600; margin-bottom: 8px;">
+                    DeepFabric Training Metrics
+                </div>
+                <p style="margin: 0; font-size: 14px; opacity: 0.9;">
+                    Enter your API key below to log training metrics.<br>
+                    Get your key at <a href="https://app.deepfabric.ai/settings/api"
+                       target="_blank" style="color: #fff;">app.deepfabric.ai/settings/api</a><br>
+                    <em>Press Enter without typing to skip.</em>
+                </p>
+            </div>
+        """
+            )
+        )
+
+        key = getpass("DeepFabric API Key: ").strip()
+    except Exception as e:
+        logger.debug(f"Colab prompt failed: {e}")
+        return None
+    else:
+        return key if key else None
+
+
+def _show_terminal_prompt() -> str | None:
+    """Show terminal input prompt.
+
+    Returns:
+        API key string or None if skipped
+    """
+    print()
+    print("=" * 60)
+    print("  DeepFabric Training Metrics")
+    print("=" * 60)
+    print()
+    print("  Enter your API key to log training metrics to DeepFabric.")
+    print("  Get your key at: https://app.deepfabric.ai/settings/api")
+    print()
+    print("  Press Enter without typing to skip (disable logging).")
+    print()
+    print("=" * 60)
+
+    try:
+        key = input("  API Key: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        print("  Logging disabled for this session.")
+        print()
+        return None
+    else:
+        print()
+        if key:
+            print("  API key set. Training metrics will be logged.")
+        else:
+            print("  Logging disabled for this session.")
+        print()
+        return key if key else None
+
+
+def get_api_key(force_prompt: bool = False) -> str | None:
+    """Get API key from environment or prompt user.
+
+    Priority:
+    1. DEEPFABRIC_API_KEY environment variable
+    2. Cached value from previous prompt
+    3. Interactive prompt (notebook widget or terminal input)
+    4. None (silently disable logging in non-interactive environments)
+
+    Args:
+        force_prompt: If True, prompt even if env var is set
+
+    Returns:
+        API key string or None if unavailable/skipped
+    """
+    global _api_key_cache, _api_key_checked  # noqa: PLW0603
+
+    # Check environment variable first
+    env_key = os.getenv("DEEPFABRIC_API_KEY")
+    if env_key and not force_prompt:
+        return env_key
+
+    # Return cached value if already checked
+    if _api_key_checked and not force_prompt:
+        return _api_key_cache
+
+    # Mark as checked to avoid repeated prompts
+    _api_key_checked = True
+
+    # Try interactive prompts
+    if _is_colab():
+        try:
+            _api_key_cache = _show_colab_prompt()
+        except Exception as e:
+            logger.debug(f"Colab prompt failed: {e}")
+        else:
+            return _api_key_cache
+
+    if _is_notebook():
+        try:
+            _api_key_cache = _show_notebook_prompt()
+        except Exception as e:
+            logger.debug(f"Notebook prompt failed: {e}")
+        else:
+            if _api_key_cache is not None:
+                return _api_key_cache
+
+    if _is_interactive_terminal():
+        try:
+            _api_key_cache = _show_terminal_prompt()
+        except Exception as e:
+            logger.debug(f"Terminal prompt failed: {e}")
+        else:
+            return _api_key_cache
+
+    # Non-interactive environment - silently disable
+    logger.debug("Non-interactive environment, auto-logging disabled")
+    _api_key_cache = None
+    return None
+
+
+def clear_api_key_cache() -> None:
+    """Clear the cached API key (for testing)."""
+    global _api_key_cache, _api_key_checked  # noqa: PLW0603
+    _api_key_cache = None
+    _api_key_checked = False