TFrameX v0.1.3 - Refactor & Critical Bug Fixes

TFrameX v0.1.3 Release Notes

This release focuses on significant internal refactoring for improved project structure, robustness, and adherence to modern Python packaging standards. It also addresses critical import issues, including circular dependencies.

There are more examples now!!!

✨ New Features & Enhancements

• Improved Project Structure: The internal layout of the tframex library has been reorganized into more logical sub-packages (agents, flows, models, patterns, util). This enhances maintainability and clarity for future development.
• Introduction of Engine Class: A new Engine class (tframex.util.engine.Engine) has been introduced to handle agent instantiation and execution logic, decoupling it from the TFrameXRuntimeContext. This promotes better separation of concerns.
• Enhanced Logging: Implemented a new logging configuration utility (tframex.util.logging.logging_config) providing colored and structured logging output by default for better debugging and operational visibility.
• Modern Packaging:
  • Transitioned primary packaging configuration to pyproject.toml, adhering to modern Python standards (PEP 517, PEP 621).
  • Updated license specification in pyproject.toml to use license = { file = "LICENSE" } and removed deprecated license classifiers, addressing setuptools deprecation warnings.
  • Corrected package discovery in pyproject.toml (changed where = ["src"] to where = ["."]) to accurately reflect the project structure, resolving build errors related to egg_base.
• Default Behavior Change for Agents: The @app.agent decorator's strip_think_tags parameter now defaults to True. This means agents will, by default, remove <think>...</think> blocks from their final output, leading to cleaner responses unless explicitly overridden.

🐛 Bug Fixes

• Critical: Resolved Circular Import: Fixed a significant circular import issue between tframex.util.engine and tframex.agents.base by deferring agent class imports within the Engine class. This resolves ImportError: cannot import name '...' from partially initialized module errors that prevented the library from loading correctly.
• Critical: Ensured Package Integrity: Added missing __init__.py files to all new subdirectories (agents, flows, models, patterns, util, util/logging). This is essential for Python to recognize these directories as importable packages and was a root cause of initial ModuleNotFoundError issues.
• Corrected Top-Level Imports: The main tframex/__init__.py has been updated to correctly re-export all public classes and functions from their new, refactored locations, ensuring a consistent API for library users.

🛠️ Internal Changes

• The TFrameXRuntimeContext now delegates agent and tool calls to the new Engine instance.
• LLMAgent constructor now accepts an engine parameter instead of app_runtime_ref.
• Flow.execute method now accepts an engine parameter instead of app_runtime.
  (Note: While these are internal, they represent breaking changes for users directly subclassing or instantiating these components outside the standard @app.agent and app.run_context() pathways.)

⚠️ Known Considerations / Potential Minor Breaking Changes for Users

• Default strip_think_tags: As mentioned, strip_think_tags for agents now defaults to True. If your application previously relied on <think> tags being present in the output by default, you might need to explicitly set strip_think_tags=False in your agent definitions.
• Advanced API for LLMAgent and Flow.execute: Users directly instantiating LLMAgent or subclassing Flow and overriding execute will need to update their code to accommodate the new engine parameter. Standard usage through TFrameXApp decorators and run_context should remain unaffected.

📦 Installation & Setup

For Users (Installing TFrameX as a library):

To install or upgrade to this version:

pip install tframex==0.1.3

Or, if installing from a local wheel:

pip install path/to/tframex-0.1.3-py3-none-any.whl

For Developers (Contributing to TFrameX or running examples from source):

If you're developing TFrameX itself or want to run examples directly from a cloned repository, we recommend setting up a dedicated virtual environment. You can use uv for its speed, or pip with venv.

Setting up with uv (Recommended):

First, install uv by following the instructions at astral.sh/uv.

Then, in your cloned TFrameX repository:

# Clone the repository (if you haven't already)
# git clone https://github.com/TesslateAI/TFrameX.git
# cd TFrameX

# Create and activate a virtual environment using uv
uv venv
source .venv/bin/activate  # On macOS/Linux
# For Windows PowerShell: .venv\Scripts\Activate.ps1
# For Windows Command Prompt: .venv\Scripts\activate.bat

# Install TFrameX in editable mode along with its dependencies.
# This command also installs the [examples] and [dev] optional dependencies
# defined in pyproject.toml, which are useful for running examples and development.
uv pip install -e ".[examples,dev]"

# Alternatively, if you only need to run examples without development tools:
# uv pip install -e ".[examples]"

# To install only the core library in editable mode:
# uv pip install -e .

This approach installs TFrameX in "editable" mode, meaning changes you make to the source code are immediately reflected in the activated virtual environment. The .[examples,dev] part installs optional dependencies grouped under examples and dev in the pyproject.toml file, which are useful for running the provided examples and for development tasks like linting and formatting.