Skip to content

Fix Import Inconsistencies and Enhance Validation#204

Merged
kovtcharov merged 9 commits intoamd:mainfrom
kovtcharov:kalin/fix-import
Jan 19, 2026
Merged

Fix Import Inconsistencies and Enhance Validation#204
kovtcharov merged 9 commits intoamd:mainfrom
kovtcharov:kalin/fix-import

Conversation

@kovtcharov
Copy link
Collaborator

@kovtcharov kovtcharov commented Jan 19, 2026 •
edited
Loading

Summary

Fixes breaking change from commit 77df07b where documentation showed incorrect import paths after LLM client refactor. Expands import validation from 4 to 31 tests to prevent future issues.

Problem

After the LLM client refactor (Jan 15), documentation showed:

from gaia.llm.llm_client import LLMClient  # ❌ ModuleNotFoundError

But the correct import is:

from gaia.llm import LLMClient  # ✅ Works

This remained undetected for 4 days, causing user confusion.

Changes

Documentation (6 files)

  • Fixed import examples in SDK docs, API reference, and playbooks
  • All examples now use canonical from gaia.llm import X pattern

Code (5 files)

  • Added VLMClient export to src/gaia/llm/__init__.py
  • Updated 3 internal files to use canonical imports
  • Created src/gaia/agents/blender/__init__.py to properly export BlenderAgent
  • Fixed 6 Pylint warnings in Blender agent

Testing (1 file)

  • Enhanced util/lint.ps1 with 31 comprehensive import tests (up from 4)
  • Tests all public SDK exports: LLM, Chat, RAG, Agents, Database, Utils
  • All imports validated on every CI run

Impact

  • ✅ Users following docs will no longer get import errors
  • ✅ Breaking changes caught in < 5 minutes (was 4 days)
  • ✅ 7.5x more import coverage (31 vs 4 tests)

Test Results

✅ ALL QUALITY CHECKS PASSED
✅ All 31 imports working
✅ Code formatting passed
✅ Import sorting passed
✅ Pylint passed
✅ Flake8 passed

@kovtcharov kovtcharov self-assigned this Jan 19, 2026
@kovtcharov kovtcharov added the devops DevOps/infrastructure changes label Jan 19, 2026
@github-actions github-actions bot added documentation Documentation changes llm LLM backend changes performance Performance-critical changes labels Jan 19, 2026
kovtcharov and others added 3 commits January 19, 2026 01:19
@kovtcharov
trigger CI re-run
44e16e4
@kovtcharov @claude
Improve lint script visibility for Black formatting errors
70d71e6 
- Show which files would be reformatted
- Display diff output with color coding
- Helps diagnose CI formatting failures

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
@kovtcharov
format w/ latest black
837a8a5
@github-actions github-actions bot added agents Agent system changes jira Jira agent changes talk Talk agent changes chat Chat SDK changes cli CLI changes tests Test changes labels Jan 19, 2026
@kovtcharov kovtcharov requested review from itomek and itomek-amd and removed request for itomek January 19, 2026 09:56
@github-actions github-actions bot added the rag RAG system changes label Jan 19, 2026
@kovtcharov kovtcharov changed the title Fix lint for incorrect import Fix Import Inconsistencies and Enhance Validation Jan 19, 2026
@kovtcharov kovtcharov enabled auto-merge January 19, 2026 09:59
@kovtcharov @claude
Add missing blender agent __init__.py
98c7611 
This file was missing from git, causing import failures in CI.
Locally it worked because the untracked file was present.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
@kovtcharov
Copy link
Collaborator Author

kovtcharov commented Jan 19, 2026

@claude review this PR.

@kovtcharov kovtcharov disabled auto-merge January 19, 2026 19:23
@github-actions
Copy link

github-actions bot commented Jan 19, 2026 •
edited
Loading

Claude finished @kovtcharov's task —— View job

PR Review: Fix Import Inconsistencies and Enhance Validation

Overall Assessment: Approved ✅

This is a well-structured PR that addresses a real user-facing issue (broken import documentation) and significantly improves the project's ability to detect future import regressions.

Summary

Category Files Assessment
Documentation 6 🟢 Clean fixes
Code 5 🟢 Good improvements
Testing 2 🟢 Comprehensive expansion

Documentation Changes 🟢

All 6 documentation files now use the canonical import pattern:

  • from gaia.llm import LLMClient (was from gaia.llm.llm_client import LLMClient)
  • from gaia.llm import VLMClient (was from gaia.llm.vlm_client import VLMClient)

Files updated:

  • docs/playbooks/emr-agent/part-1-getting-started.mdx
  • docs/sdk/api-reference.mdx
  • docs/sdk/examples.mdx
  • docs/sdk/sdks/llm.mdx
  • docs/sdk/sdks/vlm.mdx
  • docs/spec/file-change-handler.mdx

Code Changes 🟢

1. New VLMClient export (src/gaia/llm/__init__.py:8)

from .vlm_client import VLMClient
__all__ = ["create_client", "LLMClient", "VLMClient", "NotSupportedError"]

Good addition - ensures from gaia.llm import VLMClient works.

2. New BlenderAgent module (src/gaia/agents/blender/__init__.py)

from gaia.agents.blender.agent import BlenderAgent
__all__ = ["BlenderAgent"]

Correct pattern - matches other agent packages.

3. Blender agent cleanup (src/gaia/agents/blender/agent.py)

  • Removed unused f-string prefix on system prompt (line 87)
  • Renamed private functions with _ prefix (_get_object_info, _delete_object, _execute_blender_code, _diagnose_scene)

These are good Pylint fixes.

4. Internal import updates

  • src/gaia/agents/emr/agent.py:328 - Uses canonical from gaia.llm import VLMClient
  • src/gaia/agents/emr/cli.py:639 - Same
  • src/gaia/rag/sdk.py:435 - Same

5. Code style cleanup
Several files had string concatenation reformatted for consistency (multiline strings now joined inline). These are non-functional changes but improve readability.

Testing Changes 🟢

Import test expansion (util/lint.py and util/lint.ps1)

The import validation expanded from 4 to 31 tests:

Category Tests Added
LLM package 5 (LLMClient, VLMClient, create_client, NotSupportedError, module)
Chat SDK 6 (ChatSDK, ChatConfig, ChatSession, ChatResponse, quick_chat, module)
RAG SDK 4 (RAGSDK, RAGConfig, quick_rag, module)
Base Agent 4 (Agent, MCPAgent, tool, module)
Specialized Agents 7 (ChatAgent, CodeAgent, JiraAgent, DockerAgent, BlenderAgent, MedicalIntakeAgent, RoutingAgent)
Database 2 (DatabaseAgent, DatabaseMixin)
Utilities 2 (FileWatcher, FileWatcherMixin)

The test structure also improved:

  • Added Optional flag support for graceful handling of optional dependencies
  • Better error message extraction and display
  • Consistent output format between lint.py and lint.ps1

Minor Observations

🟡 Non-issue: The Blender agent function renames (get_object_info → _get_object_info, etc.) are fine since these functions are commented out with # @tool and not registered in the tool registry.

🟢 Good practice: The PR maintains parity between lint.py (cross-platform) and lint.ps1 (Windows PowerShell), ensuring CI and local development have identical behavior.

Verdict

Approve - This PR:

  1. Fixes user-facing documentation bugs
  2. Adds proper module exports for consistent imports
  3. Significantly expands CI coverage to prevent future regressions
  4. Includes appropriate Pylint fixes

The 7.5x increase in import test coverage (4 → 31) is a meaningful improvement for SDK stability.

@kovtcharov kovtcharov enabled auto-merge January 19, 2026 19:25
@kovtcharov kovtcharov added this pull request to the merge queue Jan 19, 2026
Merged via the queue into amd:main with commit 6b7f9b6 Jan 19, 2026
61 checks passed
@kovtcharov kovtcharov deleted the kalin/fix-import branch January 19, 2026 19:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@itomek itomek itomek approved these changes

@itomek-amd itomek-amd itomek-amd approved these changes

@kovtcharov-amd kovtcharov-amd Awaiting requested review from kovtcharov-amd kovtcharov-amd is a code owner

Assignees

@kovtcharov kovtcharov

Labels

agents Agent system changes chat Chat SDK changes cli CLI changes devops DevOps/infrastructure changes documentation Documentation changes jira Jira agent changes llm LLM backend changes performance Performance-critical changes rag RAG system changes talk Talk agent changes tests Test changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@kovtcharov @itomek @itomek-amd