How to Control Progress Bar Display in Semantica (Disable/Force)

You can disable or force the console progress bar in Semantica by setting the SEMANTICA_DISABLE_PROGRESS=1 or SEMANTICA_FORCE_PROGRESS=1 environment variables before the first import, or by programmatically toggling the enabled attribute on the singleton ProgressTracker instance.

Semantica provides a configurable progress tracking system that automatically detects whether it is running in an interactive terminal or a headless environment. According to the semantica-agi/semantica source code, you can control progress bar display in Semantica through environment variables or direct API manipulation of the ProgressTracker class located in semantica/utils/progress_tracker.py.

How the ProgressTracker Decides to Display Output

The ProgressTracker class (defined in semantica/utils/progress_tracker.py) initializes by detecting the execution environment through internal methods like _detect_jupyter(), _detect_tty(), and _apply_env_overrides(). By default, it enables the console progress bar only when stdout is a terminal (TTY) and not running inside a Jupyter notebook, unless explicitly overridden.

Environment variables take precedence over automatic detection:

Variable	Effect	Default
SEMANTICA_DISABLE_PROGRESS	Forces the tracker to stay disabled, regardless of environment detection	False
SEMANTICA_FORCE_PROGRESS	Overrides the automatic "no-TTY" check and forces console display even when stdout is not a terminal (e.g., in CI pipelines)	False

Disabling the Progress Bar Globally

Using the SEMANTICA_DISABLE_PROGRESS Environment Variable

To completely suppress the progress UI across all Semantica operations, set the SEMANTICA_DISABLE_PROGRESS environment variable before importing any Semantica modules:

import os
os.environ["SEMANTICA_DISABLE_PROGRESS"] = "1"

from semantica.vector_store.vector_store import VectorStore

# The progress bar is now fully suppressed during indexing operations

Programmatic Control via the Singleton

You can also disable the tracker at runtime by accessing the singleton through get_progress_tracker() (re-exported from semantica/utils/__init__.py):

from semantica.utils import get_progress_tracker

tracker = get_progress_tracker()
tracker.enabled = False

# Execute long-running operations without progress display

tracker.enabled = True  # Re-enable when needed

Forcing the Progress Bar in Non-TTY Environments

Enabling Display in CI Pipelines and Logs

When running Semantica in CI/CD pipelines or redirected output where stdout is not a TTY, use SEMANTICA_FORCE_PROGRESS to override the automatic detection:

import os

os.environ["SEMANTICA_FORCE_PROGRESS"] = "1"
os.environ.pop("SEMANTICA_DISABLE_PROGRESS", None)  # Ensure disable flag is not set

from semantica.visualization.kg_visualizer import KGVisualizer

# The visualizer will now render a progress bar even without a terminal

Working with the ProgressTracker API

The global ProgressTracker instance is managed through semantica/utils/__init__.py, which exposes get_progress_tracker() for module-wide access. Modules like semantica/vector_store/vector_store.py and semantica/visualization/kg_visualizer.py import this singleton to report operation progress.

from semantica.utils import get_progress_tracker, ProgressTracker

# Access the global instance used throughout the library

tracker = get_progress_tracker()

# Create a custom tracker instance (advanced usage)

custom_tracker = ProgressTracker(enabled=False, use_emoji=False)

The regression tests in tests/test_progress_tracker_regressions.py verify that the environment variable logic works as expected across different execution contexts.

Summary

• Set SEMANTICA_DISABLE_PROGRESS=1 before import to globally suppress the progress bar in any environment.
• Set SEMANTICA_FORCE_PROGRESS=1 to render the progress bar even when stdout is not a TTY, useful for CI/CD logs.
• Modify the enabled attribute on the get_progress_tracker() singleton for runtime control during specific operations.
• The detection logic resides in semantica/utils/progress_tracker.py and handles Jupyter, TTY, and environment override checks.

Frequently Asked Questions

Why does the progress bar appear in Jupyter notebooks but not in my Docker logs?

By default, Semantica's ProgressTracker (in semantica/utils/progress_tracker.py) detects Jupyter environments separately from standard TTY checks. If running in a container without a pseudo-TTY allocated, the automatic TTY detection disables the display unless you set SEMANTICA_FORCE_PROGRESS=1.

Can I disable the progress bar for just one specific function call?

Yes. Because get_progress_tracker() returns a singleton instance, you can temporarily toggle its enabled attribute to False before the call and restore it afterward. Alternatively, set the SEMANTICA_DISABLE_PROGRESS environment variable only for the subprocess or context where suppression is needed.

What takes precedence: the environment variable or the constructor argument?

According to the implementation in semantica/utils/progress_tracker.py, explicit constructor arguments are evaluated during initialization, but the environment variables (SEMANTICA_DISABLE_PROGRESS, SEMANTICA_FORCE_PROGRESS) are consulted in _apply_env_overrides() and can override automatic detection settings. Set these variables before the first import to ensure they take global effect.

Where are the progress tracker tests located?

The regression tests verifying environment variable handling and display logic are located in tests/test_progress_tracker_regressions.py within the semantica-agi/semantica repository.

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