add streaming

[MedGhassen]

Description

This PR add streaming support, resolves OpenAI provider bugs, adds a real OpenAI graph agent example, and fixes all mypy type errors.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Code refactoring
• Test addition/update

Related Issues

Fixes OpenAI provider type errors and runtime issues

Changes Made

1. Added Streaming support

2. Fixed OpenAI Provider Bugs (src/routekit/providers/openai.py)

• Fixed httpx import: Now imports httpx at runtime (not just in TYPE_CHECKING) so it's available in exception handlers
• Fixed content=None handling: Changed message.get("content", "") to message.get("content") or "" to properly handle cases where OpenAI returns None for content (common when tool calls are present)

3. Added Real OpenAI Example (examples/graph_agent_real.py)

• New example demonstrating graph-based agent orchestration with real OpenAI API
• Uses gpt-4o-mini for cost efficiency (can be changed to other models)
• Includes proper error handling and API key validation
• Shows complete graph workflow: Agent1 → Echo Tool → Agent2
• Includes debugging output for intermediate results

4. Fixed Type Errors

• src/routekit/core/runtime.py: Added type assertions for ModelResponse when stream=False and AsyncIterator when stream=True
• src/routekit/core/agent.py: Added type assertion for RunResult in streaming method
• All mypy type checks now pass

5. Code Formatting

• Applied ruff format to all modified files
• All files now pass formatting checks

Testing

• All existing tests pass
• New tests added (simplified streaming serve tests)
• Manual testing performed:
  • Ran test_streaming_serve.py - all tests pass without hanging
  • Ran graph_agent_real.py - successfully executes with real OpenAI API
  • Verified type checking passes with mypy src/
  • Verified linting passes with ruff check src/

Checklist

• Code follows the project's style guidelines
• Self-review completed
• Code is commented, particularly in hard-to-understand areas
• Documentation updated (example file includes usage instructions)
• No new warnings generated
• Tests added/updated (streaming serve tests refactored)
• All tests pass locally
• Type checking passes (mypy src/)
• Linting passes (ruff check src/)

Additional Notes

• The graph_agent_real.py example requires OPENAI_API_KEY environment variable to be set
• The example uses gpt-4o-mini for cost efficiency, but can be changed to other models like gpt-4 or gpt-3.5-turbo
• Test simplifications maintain coverage while avoiding the hanging issue with infinite streaming responses
• All type assertions added are runtime-safe and help mypy understand types at compile time