docs: add basic observe() example with mock OpenAI client

[amanishimwe]

Pull Request

Description

Adds a beginner-friendly examples/observe_basic.py demo for TealTiger's observe() API. It utilizes a mock OpenAI client (no API key), displays cost tracking via get_cost(), and demonstrates the freeze() / unfreeze() kill switches.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality not to work as expected)
• Documentation update
• Performance improvement
• Code refactoring
• Test improvements

Changes Made

• Added examples/observe_basic.py
• Demonstrates wrapping a mock OpenAI client with observe()
• Shows cost summary output and freeze/unfreeze behavior

Testing

Describe the tests you ran to verify your changes:

• Unit tests pass (pytest)
• Type checking passes (mypy src)
• Linting passes (ruff check src tests)
• Manual testing performed
• Added new tests for new functionality
  Manual checks:
• Ran python3 examples/observe_basic.py (call → cost → blocked → unfreeze)
• Ran ruff check examples/observe_basic.py

Checklist

• My code follows the project's code style
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Breaking Changes

None.

Screenshots (if applicable)

Not applicable.

Additional Notes

Docs/example-only PR

[amanishimwe]

CI failed at dependency install on Python 3.8; this PR only adds an example and doesn’t change package dependencies.

[amanishimwe]

@nagasatish007, when you get time, kindly review my PR#22.

Thank you

[nagasatish007]

Thanks @amanishimwe — clean example, appreciate the mock client approach (no API key needed to run it).

The CI failure on Python 3.8 is pre-existing and unrelated to your change. Merging.