v1.7.0

Fragua v1.7.0

Overview

This release introduces a structural refactor of the execution layer to align the agent with the Builder-based architecture. The changes improve separation of concerns, extensibility, and observability of pipeline executions without altering the public contract of pipelines.

---

Key Changes

Agent Refactor: Builder Integration

• The Agent class has been refactored to delegate result construction to a dedicated Result Builder.
• Execution logic is now clearly separated from result assembly, reducing responsibilities within the agent.
• This prepares the execution layer for future extensions (e.g. alternative result formats, persistence, or streaming).

run_pipeline Modernization

• run_pipeline has been updated to:
  • Focus exclusively on step execution and metadata collection.
  • Defer final result creation to _build_result_box, which now relies on the builder.
• Step execution flow remains unchanged from a consumer perspective.

Improved Execution Metadata

• Step metadata collection is now fully centralized and normalized.
• Macro-origin information is preserved and attached passively when present.
• Each step execution records:
  • Execution order
  • Set name
  • Function
  • Inputs used
  • Produced key
  • Parameters
  • Status
  • Macro origin (when applicable)

Internal Consistency

• Validation of execution results is performed before result construction.
• The final FraguaBox is now guaranteed to be built from a validated and complete execution context.

---

Backward Compatibility

• No breaking changes to:
  • Pipeline definitions
  • Registry usage
  • Public APIs
• Existing pipelines continue to execute without modification.

---

Motivation

This refactor establishes a cleaner execution lifecycle and lays the groundwork for:

• Multiple result builders
• Enhanced execution introspection
• More advanced macro and composition features

---

v1.6.3

Fragua v1.6.3

Overview

This version focuses on decoupling Fragua from any concrete DataFrame implementation and simplifying its dependency graph.

Changes

• Removed the direct dependency on pandas from the core.
• Replaced pandas.DataFrame typing with generic typing (object) where appropriate, enabling compatibility with multiple backends such as Polars.
• Reinforced Fragua’s role as a pure execution framework for pipelines, independent of any specific data processing library.
• Removed unused serializer utilities and related imports.
• Cleaned project dependencies to reflect the minimal requirements of the core.

Impact

Fragua is now fully backend-agnostic at the core level.
All data manipulation responsibilities are delegated to user-defined function sets, making it straightforward to:

• Use pandas, Polars, or any other DataFrame-like structure.
• Build parallel ecosystems (e.g., fragua-sets-pandas, fragua-sets-polars) without modifying Fragua itself.

This release strengthens Fragua’s architectural purity and long-term extensibility.

v1.6.2

Fragua v1.6.1

Overview

Fix add_pipelines environment function .

• Fixed bug that prevented registering a declarative pipeline definitions (dict[str ,Any]).

v1.6.1

Fragua v1.6.1

Macro Expansion Refinement

Summary

This patch release refines the macro expansion mechanism to better align with Fragua’s declarative execution model and to address issues detected during real-world pipeline execution.

---

Changes

Refined expand_macro behavior

• Refactored expand_macro to operate strictly on declarative step definitions (dict).
• Macro expansion now produces only normalized step dictionaries, fully compatible with the standard compilation pipeline.
• Prevents runtime objects from leaking into the macro layer.

Bug fixes

• Fixed an issue where invalid step identifiers (e.g. dictionaries instead of strings) could reach the FraguaStepIndex, causing errors such as: TypeError: unhashable type: 'dict'.

Clearer separation of responsibilities

• Macros are now limited to structural expansion only.
• Step building and execution remain exclusively part of the compilation and runtime phases.
• Reinforces the rule: macros describe pipelines; they do not build or execute steps.

Improved validation feedback

• Missing required parameters in macro-expanded steps now fail fast during compilation, providing clearer and earlier error messages to users.

---

Design Impact

• Strengthens Fragua’s purely declarative pipeline philosophy.
• Improves macro predictability, safety, and composability.
• Makes pipelines easier to edit, validate, and reason about.

---

Compatibility

• Fully backward compatible with Fragua v1.6.
• No public API changes.

v1.6

Fragua v1.6

Overview

Version v1.6 introduces a significant architectural refinement focused on declarative pipelines, clear separation of responsibilities, and improved environment ergonomics.
This release consolidates Fragua’s execution model by fully decoupling pipeline definitions from runtime execution artifacts, while strengthening support for macros and reusable step catalogs.

---

Key Highlights

1. Declarative Pipelines as First-Class Citizens

Pipelines are now stored and managed exclusively as dictionary-based definitions.

• FraguaSet no longer persists FraguaPipeline runtime objects
• Pipeline definitions (dict[str, Any]) are easier to edit, validate, and replace
• Compiled FraguaPipeline objects are now ephemeral runtime artifacts

This change improves correctness, debuggability, and user experience when iterating on pipelines.

---

2. Unified Pipeline Execution Entry Point

A new high-level API was introduced:

execute_pipeline(pipeline)

Supported inputs:

• FraguaPipeline → executed directly
• str → resolved from registry, compiled, then executed
• dict → compiled inline, then executed

This centralizes routing logic and eliminates ambiguity between compilation and execution.

---

3. Automatic StepBuilder Indexing from Sets

The environment now supports bulk registration of sets with automatic step exposure.

• New add_sets(...) API
• Callable items inside a FraguaSet automatically generate FraguaStepBuilder templates
• Respect for step_enabled flag
• StepIndex is populated eagerly and consistently

Macros (e.g. transform_chain) now resolve steps reliably without manual registration.

---

4. Separation of Registration Responsibilities

The previous generic register behavior was split into explicit, intention-revealing APIs:

• add_functions(...)
• add_pipeline_defs(...)
• add_sets(...)

Each method now has a single responsibility, improving clarity and maintainability.

---

5. Pipeline Update & Replace Support

New CRUD-style operations for pipeline definitions:

Replace Pipeline

• Fully replaces an existing pipeline definition
• Equivalent to delete + add

Update Pipeline

• Partially updates an existing pipeline definition
• Preserves unspecified fields
• Enforces immutability of pipeline name

This enables safe iteration and correction without redefining pipelines from scratch.

---

6. Improved Logging

Structured logging was added to critical execution paths:

• Pipeline compilation
• Pipeline execution
• Registration events
• Error scenarios

This improves observability and debugging during development and runtime.

---

Architectural Outcome

With v1.6, Fragua now enforces a clean and explicit separation between:

• Functions → callable ETL logic
• Steps → runtime execution units
• Pipeline Definitions → declarative configuration
• Execution → isolated, stateless runtime process

This release lays a strong foundation for future features such as versioned pipelines, validation tooling, and declarative exports.

---

Compatibility Notes

• Existing users storing FraguaPipeline instances in registry sets must migrate to dictionary-based pipeline definitions
• Runtime behavior remains consistent once pipelines are compiled

---

Summary

Fragua v1.6 is a structural maturity release.
It simplifies mental models, removes hidden state, and reinforces Fragua’s core philosophy:
explicit, declarative, and predictable ETL orchestration.

v1.5

Fragua v1.5

Overview

New Features and Improvements

1. Declarative Pipelines with Macro Support

   • Users can now define pipelines declaratively using JSON/YAML-like definitions.
   • Added support for macros (e.g., transform_chain) that expand into multiple FraguaStep objects automatically.
   • Macros can chain multiple steps, set save_as for the final step, and integrate seamlessly into pipelines.

2. Enhanced compile_pipeline()

   • Pipeline compilation now detects macros and expands them before normalization and validation.
   • Step dependencies are automatically handled.
   • Maintains backward compatibility with standard step definitions.

3. StepIndex Integration Improvements

   • Automatic creation of FraguaStepBuilder when registering functions in a set.
   • Utility sets (tagered sets) can now be created to prevent automatic step builder generation.

4. PipelineBuilder Enhancements

   • Added support for adding multiple steps at once.
   • Pipelines can now be defined fully declaratively and compiled in one step.
   • Maintains compatibility with the Agent execution flow.

5. Macro Output Handling

   • Macros can define a save_as for the last step, allowing downstream steps to reference it naturally.
   • Avoids runtime dependency issues with macro names.

Bug Fixes & Optimizations

• Minor improvements in validation and error messages during pipeline compilation.
• Streamlined internal handling of FraguaStep and FraguaStepBuilder to reduce copying overhead.

---

This release continues the focus on flexible, declarative ETL pipelines while keeping the core minimal and stable.

v1.4

Fragua v1.4

Overview

Version v1.4 introduces a new step construction and reuse layer aimed at reducing boilerplate while preserving Fragua’s core principles: immutability, explicitness, and composability.

This release adds two new foundational classes:

• FraguaStepBuilder
• FraguaStepIndex

Together, they provide a structured and safe way to define, reuse, and compose pipeline steps.

---

New Features

1. FraguaStepBuilder

The FraguaStepBuilder is a mutable builder designed to construct immutable FraguaStep instances incrementally.

Key characteristics:

• Fluent API for step configuration
• Supports method chaining:
  • .with_params()
  • .with_save_as()
  • .with_use()
• Produces immutable FraguaStep objects via .build()
• Enables safe, incremental construction of steps

Benefits:

• Reduces repetitive boilerplate when defining steps
• Keeps immutability guarantees at the final step level
• Improves readability and intent when assembling pipelines

---

2. FraguaStepIndex

The FraguaStepIndex acts as a registry for reusable step builder templates.

Key characteristics:

• Stores named FraguaStepBuilder templates
• Returns fresh builder copies on access
• Prevents shared mutable state
• Enables discoverable and explicit step composition

Benefits:

• Encourages reuse of common step patterns
• Centralizes step definitions without hiding behavior
• Supports scalable pipeline design through templates

---

Design Rationale

This release formalizes a clear separation between:

• Step definition (builders & templates)
• Step execution (immutable steps & agents)

By introducing builders and an index, Fragua improves developer ergonomics while maintaining strict execution semantics.

---

Compatibility

• Fully backward compatible
• Existing FraguaStep and FraguaPipeline usage remains unchanged
• New components are optional and additive

---

Summary

Fragua v1.4 strengthens the framework’s composability story by introducing a structured way to build and reuse steps—without compromising clarity, immutability, or control.

v1.3

Fragua v1.3

Overview

This update introduces a structural refactor to improve flexibility, extensibility, and separation of concerns in Fragua’s execution model. The main focus is decoupling hard-coded function sets from the core environment and agent, enabling dynamic and user-defined registries.

---

Key Changes

Registry & Sets

• Removed the implicit creation of the functions set from the default environment lifecycle.
• The registry now supports on-demand, named sets, allowing users to define functional boundaries such as:
  • extraction
  • utility
  • transformation
  • any custom category as needed.

FraguaEnvironment

• No longer assumes or initializes predefined sets like functions.
• Acts as an orchestrator that works against the registry generically.
• Delegates function resolution based on explicit set lookup, not hardcoded dependencies.

⚙️ FraguaAgent

• Refactored to resolve functions dynamically via registry sets.
• Eliminates tight coupling with a specific set name.
• Improves reusability and prepares the agent for more complex execution contexts.

Design Improvements

• Clearer responsibility boundaries between:
  • Environment (composition / configuration)
  • Registry (storage / lookup)
  • Agent (pure execution)
• Reduced implicit behavior and over-engineering.
• Stronger alignment with Fragua’s philosophy of minimal, explicit execution primitives.

---

Impact

• Greater control over how and when function groups are defined.
• Easier extension of Fragua without modifying core classes.
• Cleaner mental model for users building custom pipelines and execution contexts.

---

Notes

This refactor is non-feature breaking at the conceptual level, but existing code relying on the default functions set must now explicitly define and reference the appropriate registry set.

---

v1.2

Fragua v1.2

Overview

This release introduces a significant structural refactor focused on improving clarity, extensibility, and long-term maintainability of Fragua’s core, without changing its functional behavior.

---

Registry

• Added explicit support for replacing an entire FraguaSet at runtime.
• Clearly separated responsibilities between:
  • initial registration (register_set)
  • controlled replacement (replace_set)
• Reinforced the registry as the single source of truth for runtime resolution.

---

Environment

• Refactored the register and run methods into explicit, well-defined execution steps.
• Encapsulated each decision and action into private helper methods with single responsibility.
• The Environment now acts as a declarative orchestrator, improving:
  • readability
  • testability
  • future extensibility (policies, hooks, metrics).

---

Agent

• Refactored FraguaAgent following the same step-oriented approach.
• Clearly separated the phases of:
  • dependency resolution
  • step execution
  • result validation
  • FraguaBox construction
• Strengthened the agent’s role as a pure, stateless executor with no domain logic.

---

Documentation

• Added precise docstrings to all newly introduced helper methods.
• Execution flow is now self-descriptive at code level, reducing the need for external documentation.

---

Overall Impact

• Cleaner, more modular codebase aligned with pipeline-oriented architecture.
• Solid foundation for introducing observability, versioning, execution policies, or parallelism without breaking the public API.
• Substantial maintainability improvements with no breaking changes introduced.

v.1.1

Release Notes – v1.1

Features in v1.1

• Fix wrong requirement name.