[GOOD FIRST ISSUE] Fix Runtime Warnings in Console Output

[raphael-intugle]

---

name: Good First Issue
about: A beginner-friendly task perfect for first-time contributors
title: '[GOOD FIRST ISSUE] Fix Runtime Warnings in Console Output'
labels: 'good first issue, bug, user-experience'
assignees: ''

Welcome! 👋

This is a beginner-friendly issue perfect for first-time contributors to the Intugle project. We've designed this task to help you get familiar with our codebase while making a meaningful contribution.

Task Description

Fix annoying warnings that appear in the console output when users run SemanticModel.build(). These warnings clutter the output and make it harder for users to see important information.

Current Issue:
When users run the semantic model, they see multiple warnings:

1. Tqdm warning about missing ipywidgets (1 warning)
2. Pydantic warnings about field name "schema" shadowing parent attributes (6 warnings)

These warnings appear every time the code runs, creating a poor user experience.

Why This Matters

• User Experience: Clean output is professional and less confusing
• Signal vs Noise: Important messages get lost in warning clutter
• Trust: Too many warnings make users question code quality
• Jupyter Notebooks: These warnings are especially noisy in notebook outputs

What You'll Learn

• Pydantic data modeling best practices
• Python dependency management
• Field aliasing and naming conflicts
• Working with Pydantic's BaseModel
• Suppressing or fixing warnings properly

Current Warnings

Warning 1: Tqdm Progress Bar (1 occurrence)

/path/to/.venv/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. 
Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Warning 2: Pydantic Field Shadowing (6 occurrences)

/path/to/.venv/lib/python3.12/site-packages/pydantic/_internal/_fields.py:198: UserWarning: 
Field name "schema" in "Source" shadows an attribute in parent "BaseResource"
  warnings.warn(

Field name "schema" in "SnowflakeConnectionConfig" shadows an attribute in parent "SchemaBase"
Field name "schema" in "DatabricksSQLConnectorConfig" shadows an attribute in parent "SchemaBase"
Field name "schema" in "DatabricksNotebookConfig" shadows an attribute in parent "SchemaBase"
Field name "schema" in "PostgresConnectionConfig" shadows an attribute in parent "SchemaBase"
Field name "schema" in "SQLServerConnectionConfig" shadows an attribute in parent "SchemaBase"

Step-by-Step Guide

Prerequisites

• Python 3.10+ installed
• Git basics (clone, commit, push, pull request)
• Read our CONTRIBUTING.md guide
• Basic understanding of Pydantic models

Setup Instructions

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/data-tools.git
   cd data-tools

2. Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -e ".[dev]"

4. Create a new branch

   git checkout -b fix/resolve-runtime-warnings

5. Reproduce the warnings

   # Run a quickstart notebook to see the warnings
   jupyter notebook notebooks/quickstart_healthcare.ipynb
   # Or run tests
   pytest tests/

Implementation Steps

Part 1: Fix Tqdm Warning (Easiest)

Option A: Add ipywidgets to dependencies (Recommended)

1. Open pyproject.toml
2. Add ipywidgets to the dependencies list:

   dependencies = [
       # ... existing dependencies ...
       "ipywidgets>=8.0.0",
   ]

Option B: Suppress the warning

If adding ipywidgets causes issues, you can suppress the warning:

1. Create/modify a warning filter in the main entry point
2. Add at the top of src/intugle/semantic_model.py:

   import warnings
   warnings.filterwarnings('ignore', category=TqdmWarning)

Part 2: Fix Pydantic Field Shadowing Warnings

The issue is that multiple config classes define a field named schema, which shadows Pydantic's built-in schema() method from BaseModel.

Solution: Use Pydantic Field Aliases

The best approach is to use field aliases to keep the external API the same while using a different internal name.

Files to modify:

1. src/intugle/models/resources/source.py (line 33)

   # Before
   class Source(BaseResource):
       schema: str
       database: str
       # ...
   
   # After
   from pydantic import Field
   
   class Source(BaseResource):
       db_schema: str = Field(alias="schema")
       database: str
       # ...

Important Notes:

• The alias="schema" ensures that YAML files, JSON, and external APIs still use "schema"
• Internal code can use either obj.db_schema or obj.schema (both work with Pydantic v2)
• This is a non-breaking change for external users
• You may need to update internal code that accesses .schema to use .db_schema

Testing Your Changes

1. Run the code and verify no warnings appear:

   # Test with a simple script
   python -c "
   from intugle import SemanticModel
   datasets = {'test': {'path': 'sample_data/healthcare/patients.csv', 'type': 'csv'}}
   sm = SemanticModel(datasets, domain='Healthcare')
   "
   # Should see NO warnings

2. Run existing tests:

   # Run all tests to ensure nothing broke
   pytest tests/
   
   # Run specific adapter tests
   pytest tests/adapters/

3. Test in a notebook:

   jupyter notebook notebooks/quickstart_healthcare.ipynb
   # Run through the notebook - warnings should be gone

Submitting Your Work

1. Commit your changes

   git add pyproject.toml src/intugle/models/resources/source.py src/intugle/adapters/
   git commit -m "Fix runtime warnings: add ipywidgets and resolve Pydantic field shadowing"

2. Push to your fork

   git push origin fix/resolve-runtime-warnings

3. Create a Pull Request

   • Go to the original repository
   • Click "Pull Requests" → "New Pull Request"
   • Select your branch
   • Fill out the PR template
   • Reference this issue with "Fixes #ISSUE_NUMBER"
   • Include before/after screenshots showing warnings removed

Expected Outcome

After your changes:

• ✅ No tqdm warnings about ipywidgets
• ✅ No Pydantic warnings about field shadowing
• ✅ All tests pass
• ✅ YAML serialization still works correctly
• ✅ External API unchanged (backwards compatible)
• ✅ Clean console output when running semantic model

Definition of Done

• Tqdm warning resolved (ipywidgets added or warning suppressed)
• All 6 Pydantic field shadowing warnings resolved
• Field aliases properly configured with alias="schema"
• YAML/JSON serialization tested and works
• All existing tests pass
• No new warnings introduced
• Code tested in Jupyter notebook
• PR includes before/after evidence
• Pull request submitted

Resources

• Pydantic Field Aliases Documentation
• Pydantic BaseModel Documentation
• Python Warnings Module
• ipywidgets Documentation
• Project Documentation
• CONTRIBUTING.md

Need Help?

Don't hesitate to ask questions! We're here to help you succeed.

• Comment below with your questions
• Join our Discord for real-time support
• Tag maintainers: @raphael-intugle (if specific help needed)

Skills You'll Use

• Python basics
• Git and GitHub
• Pydantic data modeling
• Understanding field aliases
• Dependency management
• Testing and validation

---

Thank you for contributing to Intugle!

Tips for Success:

• Start with the tqdm warning (easier) to build confidence
• Make sure to import Field from pydantic in each file
• Test YAML serialization to ensure aliases work correctly
• Use model_dump(by_alias=True) to verify external representation
• Run notebooks to see the clean output!
• Have fun! 🎉

Alternative Approach:
If field aliases cause any issues, you could also:

1. Rename the field to db_schema everywhere (breaking change)
2. Update all references in the codebase
3. Update YAML loading/saving logic
   This is more work but might be cleaner long-term. Discuss in the PR if interested!

[Mohitlikestocode]

Hey @raphael-intugle!

I would really love to work on this issue, this seems interesting and something in the domain which I am familiar with.

Requesting you to kindly assign me this issue!

[raphael-intugle]

Go ahead ! @Mohitlikestocode

[raphael-intugle]

Closed