feat: semantic operators src updates - improved type composition and transduction

[D3f0]

Overview

This PR introduces significant improvements to the Agentics framework's type composition system and transduction capabilities, with a focus on semantic operators and improved data handling.

Changes

Core Dependencies

• Added duckdb>=1.4.3 for efficient data querying
• Added pandas>=2.3.3 for enhanced data manipulation
• Added async-lru>=2.0.5 for async caching capabilities

Type System Enhancements (src/agentics/core/atype.py)

• Added comprehensive docstring to pydantic_model_from_dict() function explaining:
  • Dynamic Pydantic model creation from sample dictionaries
  • Type inference and field name normalization
  • Usage examples and edge cases
• Renamed composition fields from left/right to target/source for semantic clarity:
  • target: The destination type in a composition
  • source: The source type in a composition
• Removed debug print statement from create_pydantic_model()

Default Types (src/agentics/core/default_types.py)

• Added Abool type: A new semantic type for boolean values with type validation
  • Ensures only boolean values are accepted during construction
  • Follows the same pattern as existing Astr type

Transduction Improvements (src/agentics/core/transducible_functions.py)

• Enhanced Transduce class with string representation methods:
  • Added __str__(): Human-readable string output
  • Added __repr__(): Developer-friendly representation
  • Added _one_to_str(): Handles Pydantic models, dicts, lists, and generic types
• Added new parameters to transducible() decorator:
  • transduce_fields: List of specific fields to transduce
  • prompt_template: Custom prompt template for transduction
• Fixed transduction return type: Now returns TransductionResult consistently
• Fixed generate_prototypical_instances(): Updated field definition to use optional list

Core AG Enhancements (src/agentics/core/agentics.py)

• Improved batch processing:
  • Transduction now chunks inputs using amap_batch_size for better memory management
  • Processes chunks sequentially to handle large datasets
• Fixed state merging logic:
  • Now filters output fields against allowed model fields (Pydantic v2 compatibility)
  • Prevents errors from extra fields in merged states
  • Validates AG lengths before merging
• Enhanced explanation generation:
  • Improved prompt instructions for better semantic understanding
  • Renamed explanation variables for clarity (left/right → target/source)
  • Added confidence scoring guidance to LLM
• Improved compose_states() method:
  • Changed from nested loops to paired zip() iteration (matching AG lengths)
  • Fixed semantic naming: left/right → target/source
  • More efficient and semantically correct composition
• Better error handling:
  • Added validation in merge_states() to check length compatibility
  • Meaningful error messages for debugging
• Truncated display names: Limited AG names to 30 characters in progress descriptions

Technical Benefits

1. Better Memory Management: Chunked transduction prevents memory overload with large datasets
2. Semantic Clarity: Renamed fields improve code readability and reduce confusion
3. Type Safety: Added type validation for new Abool type
4. Enhanced Debugging: Improved string representations for Transduce objects
5. Pydantic v2 Compatibility: Fixed field filtering in state merging
6. Better Explanations: Improved LLM instructions for more meaningful semantic transductions