[QA] Standardize AI Kit errors & logging consistency

[dineshpinto]

• Description
  • Standardize errors and logs so users get actionable, stable signals across modules.
• Scope
  • Use flare_ai_kit.common.exceptions uniformly; add/align specific exception types where gaps exist.
  • Replace ad-hoc raises with the standardized exceptions; keep messages concise and actionable.
  • Make logging structured and consistent (levels, no secrets/keys in logs). Use structlog semantics.
  • Document common failure modes and how to handle them.
• Acceptance criteria
  • All public functions raise documented exceptions from the common module.
  • No plaintext secrets/tokens in logs; sensitive values masked.
  • A short “Troubleshooting” section in docs/ mapping exceptions → likely causes → fixes.
  • CI green; no behavior changes to happy paths.
• Deliverables
  • Updated annotations across src/.
  • List of remaining suppressions with reasons (in PR description).
• Key Files Involved (Proposed)
  • src/flare_ai_kit/common/exceptions.py
  • All modules under src/flare_ai_kit/** that raise/log
  • docs/*.md (addtroubleshooting.md)

[manny-uncharted]

Hi, I'd like to work on this issue. I have experience with using structlog in Python, and I'm currently reviewing the exception patterns across modules

[DanielEmmanuel1]

Good day @dineshpinto, My name is Daniel and I'll like to work on this issue.

I'm a software developer with experience working with exception handling and logging in Python, I’ve also previously standardized error structures and implemented structured logging with tools like structlog and logging, and written clear documentation to help users quickly understand and resolve issues.

For this task, I’d approach it by first reviewing the existing ad-hoc raises and aligning them with flare_ai_kit.common.exceptions, making sure messages are clear and actionable. I’d then update logging calls to follow a structured format while masking sensitive data, and finally add a troubleshooting section that maps exceptions to their causes and potential fixes.

I believe in my ability to complete this issue and would love the opportunity of working on it, have a good day.

Recommended by OnlyDust for exceptional experience, quality, and reliability.

[big14way]

@dineshpinto please asssign me this issue

[DanielEmmanuel1]

I will get right on it

[DanielEmmanuel1]

@dineshpinto Please go through my PR