mojentic 0.8.3__py3-none-any.whl → 0.9.0__py3-none-any.whl

mojentic/llm/gateways/openai.py

@@ -1,6 +1,7 @@
 import json
+import os
 from itertools import islice
-from typing import Type, List, Iterable, Optional
+from typing import Type, List, Iterable, Optional, Iterator, Dict
 
 import numpy as np
 import structlog
@@ -13,6 +14,7 @@ from mojentic.llm.gateways.openai_messages_adapter import adapt_messages_to_open
 from mojentic.llm.gateways.openai_model_registry import get_model_registry, ModelType
 from mojentic.llm.gateways.tokenizer_gateway import TokenizerGateway
 from mojentic.llm.tools.llm_tool import LLMTool
+from mojentic.llm.gateways.ollama import StreamingResponse
 
 logger = structlog.get_logger()
 
@@ -23,11 +25,19 @@ class OpenAIGateway(LLMGateway):
 
     Parameters
     ----------
-    api_key : str
-        The OpenAI API key to use.
+    api_key : str, optional
+        The OpenAI API key to use. If not provided, defaults to the value of the
+        OPENAI_API_KEY environment variable.
+    base_url : str, optional
+        The base URL for the OpenAI API. If not provided, defaults to the value of the
+        OPENAI_API_ENDPOINT environment variable, or None if not set.
     """
 
-    def __init__(self, api_key: str, base_url: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        if api_key is None:
+            api_key = os.getenv("OPENAI_API_KEY")
+        if base_url is None:
+            base_url = os.getenv("OPENAI_API_ENDPOINT")
         self.client = OpenAI(api_key=api_key, base_url=base_url)
         self.model_registry = get_model_registry()
 
@@ -292,6 +302,200 @@ class OpenAIGateway(LLMGateway):
             tool_calls=tool_calls,
         )
 
+    def complete_stream(self, **kwargs) -> Iterator[StreamingResponse]:
+        """
+        Stream the LLM response from OpenAI service.
+
+        OpenAI streams tool call arguments incrementally, so we need to accumulate them
+        and yield complete tool calls only when the stream finishes.
+
+        Keyword Arguments
+        ----------------
+        model : str
+            The name of the model to use.
+        messages : List[LLMMessage]
+            A list of messages to send to the LLM.
+        tools : Optional[List[LLMTool]]
+            A list of tools to use with the LLM. Tool calls will be accumulated and yielded when complete.
+        temperature : float, optional
+            The temperature to use for the response. Defaults to 1.0.
+        num_ctx : int, optional
+            The number of context tokens to use. Defaults to 32768.
+        max_tokens : int, optional
+            The maximum number of tokens to generate. Defaults to 16384.
+        num_predict : int, optional
+            The number of tokens to predict. Defaults to no limit.
+
+        Returns
+        -------
+        Iterator[StreamingResponse]
+            An iterator of StreamingResponse objects containing response chunks.
+        """
+        # Extract parameters from kwargs with defaults
+        model = kwargs.get('model')
+        messages = kwargs.get('messages')
+        object_model = kwargs.get('object_model', None)
+        tools = kwargs.get('tools', None)
+        temperature = kwargs.get('temperature', 1.0)
+        num_ctx = kwargs.get('num_ctx', 32768)
+        max_tokens = kwargs.get('max_tokens', 16384)
+        num_predict = kwargs.get('num_predict', -1)
+
+        if not model:
+            raise ValueError("'model' parameter is required")
+        if not messages:
+            raise ValueError("'messages' parameter is required")
+
+        # Convert parameters to dict for processing
+        args = {
+            'model': model,
+            'messages': messages,
+            'object_model': object_model,
+            'tools': tools,
+            'temperature': temperature,
+            'num_ctx': num_ctx,
+            'max_tokens': max_tokens,
+            'num_predict': num_predict
+        }
+
+        # Adapt parameters based on model type
+        try:
+            adapted_args = self._adapt_parameters_for_model(model, args)
+        except Exception as e:
+            logger.error("Failed to adapt parameters for model",
+                        model=model,
+                        error=str(e))
+            raise
+
+        # Validate parameters after adaptation
+        self._validate_model_parameters(model, adapted_args)
+
+        # Check if model supports streaming
+        capabilities = self.model_registry.get_model_capabilities(model)
+        if not capabilities.supports_streaming:
+            raise NotImplementedError(f"Model {model} does not support streaming")
+
+        # Structured output doesn't work with streaming
+        if adapted_args['object_model'] is not None:
+            raise NotImplementedError("Streaming with structured output (object_model) is not supported")
+
+        openai_args = {
+            'model': adapted_args['model'],
+            'messages': adapt_messages_to_openai(adapted_args['messages']),
+            'stream': True,
+        }
+
+        # Add temperature if specified
+        if 'temperature' in adapted_args:
+            openai_args['temperature'] = adapted_args['temperature']
+
+        if adapted_args.get('tools') is not None:
+            openai_args['tools'] = [t.descriptor for t in adapted_args['tools']]
+
+        # Handle both max_tokens (for chat models) and max_completion_tokens (for reasoning models)
+        if 'max_tokens' in adapted_args:
+            openai_args['max_tokens'] = adapted_args['max_tokens']
+        elif 'max_completion_tokens' in adapted_args:
+            openai_args['max_completion_tokens'] = adapted_args['max_completion_tokens']
+
+        logger.debug("Making OpenAI streaming API call",
+                    model=openai_args['model'],
+                    has_tools='tools' in openai_args,
+                    token_param='max_completion_tokens' if 'max_completion_tokens' in openai_args else 'max_tokens')
+
+        try:
+            stream = self.client.chat.completions.create(**openai_args)
+        except BadRequestError as e:
+            if "max_tokens" in str(e) and "max_completion_tokens" in str(e):
+                logger.error("Parameter error detected - model may require different token parameter",
+                            model=model,
+                            error=str(e),
+                            suggestion="This model may be a reasoning model requiring max_completion_tokens")
+            raise e
+        except Exception as e:
+            logger.error("OpenAI streaming API call failed",
+                        model=model,
+                        error=str(e))
+            raise e
+
+        # Accumulate tool calls as they stream in
+        # OpenAI streams tool arguments incrementally, indexed by tool call index
+        tool_calls_accumulator: Dict[int, Dict] = {}
+
+        for chunk in stream:
+            if not chunk.choices:
+                continue
+
+            delta = chunk.choices[0].delta
+            finish_reason = chunk.choices[0].finish_reason
+
+            # Yield content chunks as they arrive
+            if delta.content:
+                yield StreamingResponse(content=delta.content)
+
+            # Accumulate tool call chunks
+            if delta.tool_calls:
+                for tool_call_delta in delta.tool_calls:
+                    index = tool_call_delta.index
+
+                    # Initialize accumulator for this tool call if needed
+                    if index not in tool_calls_accumulator:
+                        tool_calls_accumulator[index] = {
+                            'id': None,
+                            'name': None,
+                            'arguments': ''
+                        }
+
+                    # First chunk has id and name
+                    if tool_call_delta.id:
+                        tool_calls_accumulator[index]['id'] = tool_call_delta.id
+
+                    if tool_call_delta.function.name:
+                        tool_calls_accumulator[index]['name'] = tool_call_delta.function.name
+
+                    # All chunks may have argument fragments
+                    if tool_call_delta.function.arguments:
+                        tool_calls_accumulator[index]['arguments'] += tool_call_delta.function.arguments
+
+            # When stream is complete, yield accumulated tool calls
+            if finish_reason == 'tool_calls' and tool_calls_accumulator:
+                # Parse and yield complete tool calls
+                complete_tool_calls = []
+                for index in sorted(tool_calls_accumulator.keys()):
+                    tc = tool_calls_accumulator[index]
+                    try:
+                        # Parse the accumulated JSON arguments
+                        args_dict = json.loads(tc['arguments'])
+                        # Convert to string values as per LLMToolCall format
+                        arguments = {str(k): str(v) for k, v in args_dict.items()}
+
+                        tool_call = LLMToolCall(
+                            id=tc['id'],
+                            name=tc['name'],
+                            arguments=arguments
+                        )
+                        complete_tool_calls.append(tool_call)
+                    except json.JSONDecodeError as e:
+                        logger.error("Failed to parse tool call arguments",
+                                   tool_name=tc['name'],
+                                   arguments=tc['arguments'],
+                                   error=str(e))
+
+                if complete_tool_calls:
+                    # Convert to the format expected by ollama's tool calls for compatibility
+                    # We need to create mock objects that match ollama's structure
+                    from types import SimpleNamespace
+                    ollama_format_calls = []
+                    for tc in complete_tool_calls:
+                        ollama_format_calls.append(SimpleNamespace(
+                            id=tc.id,  # Include ID for proper OpenAI message formatting
+                            function=SimpleNamespace(
+                                name=tc.name,
+                                arguments=tc.arguments
+                            )
+                        ))
+                    yield StreamingResponse(tool_calls=ollama_format_calls)
+
     def get_available_models(self) -> list[str]:
         """
         Get the list of available OpenAI models, sorted alphabetically.

mojentic/llm/gateways/openai_spec.py

@@ -0,0 +1,99 @@
+import os
+from unittest.mock import patch
+
+from mojentic.llm.gateways.openai import OpenAIGateway
+
+
+class DescribeOpenAIGateway:
+    """
+    Unit tests for the OpenAI gateway
+    """
+
+    class DescribeInitialization:
+        """
+        Tests for OpenAI gateway initialization
+        """
+
+        def should_initialize_with_api_key(self, mocker):
+            api_key = "test-api-key"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            gateway = OpenAIGateway(api_key=api_key)
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=None)
+            assert gateway.client is not None
+
+        def should_initialize_with_api_key_and_base_url(self, mocker):
+            api_key = "test-api-key"
+            base_url = "https://custom.openai.com"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            gateway = OpenAIGateway(api_key=api_key, base_url=base_url)
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=base_url)
+            assert gateway.client is not None
+
+        def should_read_api_key_from_environment_variable(self, mocker):
+            api_key = "test-api-key-from-env"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {'OPENAI_API_KEY': api_key}):
+                gateway = OpenAIGateway()
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=None)
+            assert gateway.client is not None
+
+        def should_read_base_url_from_environment_variable(self, mocker):
+            api_key = "test-api-key"
+            endpoint = "https://corporate.openai.com"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {'OPENAI_API_ENDPOINT': endpoint}):
+                gateway = OpenAIGateway(api_key=api_key)
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=endpoint)
+            assert gateway.client is not None
+
+        def should_read_both_from_environment_variables(self, mocker):
+            api_key = "test-api-key-from-env"
+            endpoint = "https://corporate.openai.com"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {'OPENAI_API_KEY': api_key, 'OPENAI_API_ENDPOINT': endpoint}):
+                gateway = OpenAIGateway()
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=endpoint)
+            assert gateway.client is not None
+
+        def should_prefer_explicit_api_key_over_environment_variable(self, mocker):
+            api_key_env = "test-api-key-from-env"
+            api_key_explicit = "test-api-key-explicit"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {'OPENAI_API_KEY': api_key_env}):
+                gateway = OpenAIGateway(api_key=api_key_explicit)
+
+            mock_openai.assert_called_once_with(api_key=api_key_explicit, base_url=None)
+            assert gateway.client is not None
+
+        def should_prefer_explicit_base_url_over_environment_variable(self, mocker):
+            api_key = "test-api-key"
+            endpoint_env = "https://corporate.openai.com"
+            endpoint_explicit = "https://explicit.openai.com"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {'OPENAI_API_ENDPOINT': endpoint_env}):
+                gateway = OpenAIGateway(api_key=api_key, base_url=endpoint_explicit)
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=endpoint_explicit)
+            assert gateway.client is not None
+
+        def should_use_none_when_no_endpoint_specified(self, mocker):
+            api_key = "test-api-key"
+            mock_openai = mocker.patch('mojentic.llm.gateways.openai.OpenAI')
+
+            with patch.dict(os.environ, {}, clear=True):
+                gateway = OpenAIGateway(api_key=api_key)
+
+            mock_openai.assert_called_once_with(api_key=api_key, base_url=None)
+            assert gateway.client is not None

mojentic/llm/llm_broker.py

@@ -1,13 +1,13 @@
 import json
 import time
-from typing import List, Optional, Type
+from typing import List, Optional, Type, Iterator
 
 import structlog
 from pydantic import BaseModel
 
 from mojentic.llm.gateways.llm_gateway import LLMGateway
-from mojentic.llm.gateways.models import MessageRole, LLMMessage, LLMGatewayResponse
-from mojentic.llm.gateways.ollama import OllamaGateway
+from mojentic.llm.gateways.models import MessageRole, LLMMessage, LLMGatewayResponse, LLMToolCall
+from mojentic.llm.gateways.ollama import OllamaGateway, StreamingResponse
 from mojentic.llm.gateways.tokenizer_gateway import TokenizerGateway
 from mojentic.tracer.tracer_system import TracerSystem
 
@@ -182,6 +182,164 @@ class LLMBroker():
 
         return result.content
 
+    def generate_stream(self, messages: List[LLMMessage], tools=None, temperature=1.0, num_ctx=32768,
+                       num_predict=-1, max_tokens=16384,
+                       correlation_id: str = None) -> Iterator[str]:
+        """
+        Generate a streaming text response from the LLM.
+
+        This method mirrors generate() but yields content chunks as they arrive from the LLM,
+        providing a better user experience for long-running requests. When tool calls are
+        detected, tools are executed and the LLM is called recursively, with the new response
+        also being streamed.
+
+        Parameters
+        ----------
+        messages : List[LLMMessage]
+            A list of messages to send to the LLM.
+        tools : List[Tool]
+            A list of tools to use with the LLM. If a tool call is requested, the tool will be
+            called and the output will be included in the response.
+        temperature : float
+            The temperature to use for the response. Defaults to 1.0
+        num_ctx : int
+            The number of context tokens to use. Defaults to 32768.
+        num_predict : int
+            The number of tokens to predict. Defaults to no limit.
+        max_tokens : int
+            The maximum number of tokens to generate. Defaults to 16384.
+        correlation_id : str
+            UUID string that is copied from cause-to-affect for tracing events.
+
+        Yields
+        ------
+        str
+            Content chunks as they arrive from the LLM.
+        """
+        # Check if gateway supports streaming
+        if not hasattr(self.adapter, 'complete_stream'):
+            raise NotImplementedError(f"Gateway {type(self.adapter).__name__} does not support streaming")
+
+        approximate_tokens = len(self.tokenizer.encode(self._content_to_count(messages)))
+        logger.info(f"Requesting streaming llm response with approx {approximate_tokens} tokens")
+
+        # Convert messages to serializable dict for audit
+        messages_for_tracer = [m.model_dump() for m in messages]
+
+        # Record LLM call in tracer
+        tools_for_tracer = [{"name": t.name, "description": t.description} for t in
+                            tools] if tools else None
+        self.tracer.record_llm_call(
+            self.model,
+            messages_for_tracer,
+            temperature,
+            tools=tools_for_tracer,
+            source=type(self),
+            correlation_id=correlation_id
+        )
+
+        # Measure call duration for audit
+        start_time = time.time()
+
+        # Accumulate content and tool calls from stream
+        accumulated_content = ""
+        accumulated_tool_calls = []
+
+        stream = self.adapter.complete_stream(
+            model=self.model,
+            messages=messages,
+            tools=tools,
+            temperature=temperature,
+            num_ctx=num_ctx,
+            num_predict=num_predict,
+            max_tokens=max_tokens
+        )
+
+        for chunk in stream:
+            # Handle content chunks
+            if hasattr(chunk, 'content') and chunk.content:
+                accumulated_content += chunk.content
+                yield chunk.content
+
+            # Handle tool calls if present
+            if hasattr(chunk, 'tool_calls') and chunk.tool_calls:
+                accumulated_tool_calls.extend(chunk.tool_calls)
+
+        call_duration_ms = (time.time() - start_time) * 1000
+
+        # Record LLM response in tracer
+        tool_calls_for_tracer = [tc.model_dump() if hasattr(tc, 'model_dump') else tc for tc in
+                                 accumulated_tool_calls] if accumulated_tool_calls else None
+        self.tracer.record_llm_response(
+            self.model,
+            accumulated_content,
+            tool_calls=tool_calls_for_tracer,
+            call_duration_ms=call_duration_ms,
+            source=type(self),
+            correlation_id=correlation_id
+        )
+
+        # Process tool calls if any were accumulated
+        if accumulated_tool_calls and tools is not None:
+            logger.info("Tool call requested in streaming response")
+            for tool_call in accumulated_tool_calls:
+                # Handle both LLMToolCall objects and raw tool call data
+                if hasattr(tool_call, 'name'):
+                    tool_name = tool_call.name
+                    tool_arguments = tool_call.arguments
+                else:
+                    # Handle ollama's tool call format
+                    tool_name = tool_call.function.name
+                    tool_arguments = tool_call.function.arguments
+
+                if tool := next((t for t in tools if t.matches(tool_name)), None):
+                    logger.info('Calling function', function=tool_name)
+                    logger.info('Arguments:', arguments=tool_arguments)
+
+                    # Measure tool execution time
+                    tool_start_time = time.time()
+
+                    # Call the tool
+                    output = tool.run(**tool_arguments)
+
+                    tool_duration_ms = (time.time() - tool_start_time) * 1000
+
+                    # Record tool call in tracer
+                    self.tracer.record_tool_call(
+                        tool_name,
+                        tool_arguments,
+                        output,
+                        caller="LLMBroker.generate_stream",
+                        call_duration_ms=tool_duration_ms,
+                        source=type(self),
+                        correlation_id=correlation_id
+                    )
+
+                    logger.info('Function output', output=output)
+
+                    # Convert to LLMToolCall if needed, preserving the ID if it exists
+                    if not isinstance(tool_call, LLMToolCall):
+                        # Extract ID if available from the tool_call object
+                        tool_call_id = None
+                        if hasattr(tool_call, 'id'):
+                            tool_call_id = tool_call.id
+                        elif hasattr(tool_call, 'function') and hasattr(tool_call.function, 'id'):
+                            tool_call_id = tool_call.function.id
+
+                        tool_call = LLMToolCall(id=tool_call_id, name=tool_name, arguments=tool_arguments)
+
+                    messages.append(LLMMessage(role=MessageRole.Assistant, tool_calls=[tool_call]))
+                    messages.append(
+                        LLMMessage(role=MessageRole.Tool, content=json.dumps(output),
+                                   tool_calls=[tool_call]))
+
+                    # Recursively stream the response after tool execution
+                    yield from self.generate_stream(messages, tools, temperature, num_ctx, num_predict,
+                                                   max_tokens, correlation_id=correlation_id)
+                    return  # Exit after recursive call
+                else:
+                    logger.warn('Function not found', function=tool_name)
+
     def _content_to_count(self, messages: List[LLMMessage]):
         content = ""
         for message in messages:

mojentic/llm/llm_broker_spec.py

@@ -135,3 +135,72 @@ class DescribeLLMBroker:
             assert result.items[1].number == 2
             assert result.metadata == {"key1": "value1", "key2": "value2"}
             mock_gateway.complete.assert_called_once()
+
+    class DescribeStreamingGeneration:
+
+        def should_stream_simple_response(self, llm_broker, mock_gateway, mocker):
+            from mojentic.llm.gateways.ollama import StreamingResponse
+
+            messages = [LLMMessage(role=MessageRole.User, content="Tell me a story")]
+
+            # Mock the complete_stream method to yield chunks
+            mock_gateway.complete_stream = mocker.MagicMock()
+            mock_gateway.complete_stream.return_value = iter([
+                StreamingResponse(content="Once "),
+                StreamingResponse(content="upon "),
+                StreamingResponse(content="a "),
+                StreamingResponse(content="time...")
+            ])
+
+            result_chunks = list(llm_broker.generate_stream(messages))
+
+            assert result_chunks == ["Once ", "upon ", "a ", "time..."]
+            mock_gateway.complete_stream.assert_called_once()
+
+        def should_handle_tool_calls_during_streaming(self, llm_broker, mock_gateway, mocker):
+            from mojentic.llm.gateways.ollama import StreamingResponse
+
+            messages = [LLMMessage(role=MessageRole.User, content="What is the date on Friday?")]
+            tool_call = mocker.create_autospec(LLMToolCall, instance=True)
+            tool_call.name = "resolve_date"
+            tool_call.arguments = {"date": "Friday"}
+
+            # First stream has tool call, second stream has the response after tool execution
+            mock_gateway.complete_stream = mocker.MagicMock()
+            mock_gateway.complete_stream.side_effect = [
+                iter([
+                    StreamingResponse(content="Let "),
+                    StreamingResponse(content="me "),
+                    StreamingResponse(content="check..."),
+                    StreamingResponse(tool_calls=[tool_call])
+                ]),
+                iter([
+                    StreamingResponse(content="The "),
+                    StreamingResponse(content="date "),
+                    StreamingResponse(content="is "),
+                    StreamingResponse(content="2024-11-15")
+                ])
+            ]
+
+            mock_tool = mocker.MagicMock()
+            mock_tool.matches.return_value = True
+            mock_tool.run.return_value = {"resolved_date": "2024-11-15"}
+
+            result_chunks = list(llm_broker.generate_stream(messages, tools=[mock_tool]))
+
+            # Should get chunks from first response, then chunks from second response after tool execution
+            assert result_chunks == ["Let ", "me ", "check...", "The ", "date ", "is ", "2024-11-15"]
+            assert mock_gateway.complete_stream.call_count == 2
+            mock_tool.run.assert_called_once_with(date="Friday")
+
+        def should_raise_error_if_gateway_does_not_support_streaming(self, llm_broker, mock_gateway):
+            messages = [LLMMessage(role=MessageRole.User, content="Hello")]
+
+            # Remove complete_stream method to simulate unsupported gateway
+            if hasattr(mock_gateway, 'complete_stream'):
+                delattr(mock_gateway, 'complete_stream')
+
+            with pytest.raises(NotImplementedError) as exc_info:
+                list(llm_broker.generate_stream(messages))
+
+            assert "does not support streaming" in str(exc_info.value)

mojentic/llm/registry/populate_registry_from_ollama.py

@@ -24,9 +24,9 @@ def register_llms_from_ollama(url: str, registry: LLMRegistry):
         #         'quantization_level': 'Q4_K_M'
         #     },
         #     'digest': '4bd6cbf2d094264457a17aab6bd6acd1ed7a72fb8f8be3cfb193f63c78dd56df',
-        #     'model': 'qwen2.5-coder:32b',
+        #     'model': 'qwen3-coder:32b',
         #     'modified_at': '2025-01-29T22:37:29.191797577-05:00',
-        #     'name': 'qwen2.5-coder:32b',
+        #     'name': 'qwen3-coder:32b',
         #     'size': 19851349856
         # }
 

{mojentic-0.8.3.dist-info → mojentic-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mojentic
-Version: 0.8.3
+Version: 0.9.0
 Summary: Mojentic is an agentic framework that aims to provide a simple and flexible way to assemble teams of agents to solve complex problems.
 Author-email: Stacey Vetzal <stacey@vetzal.com>
 Project-URL: Homepage, https://github.com/svetzal/mojentic
@@ -29,6 +29,8 @@ Requires-Dist: pytest-spec; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: pip-audit>=2.0.0; extra == "dev"
 Requires-Dist: mkdocs; extra == "dev"
 Requires-Dist: mkdocs-material; extra == "dev"
 Requires-Dist: mkdocs-llmstxt; extra == "dev"
@@ -91,7 +93,7 @@ openai_llm = LLMBroker(model="gpt-5", gateway=OpenAIGateway(api_key="your_api_ke
 # Or use other models: "gpt-4o", "gpt-4.1", "o1-mini", "o3-mini", etc.
 
 # Or use Ollama for local LLMs
-ollama_llm = LLMBroker(model="llama3")
+ollama_llm = LLMBroker(model="qwen3:32b")
 
 # Simple text generation
 result = openai_llm.generate(messages=[LLMMessage(content='Hello, how are you?')])
@@ -121,6 +123,35 @@ result = openai_llm.generate(messages=[
 print(result)
 ```
 
+## 🔑 OpenAI configuration
+
+OpenAIGateway now supports environment-variable defaults so you can get started without hardcoding secrets:
+
+- If you omit `api_key`, it will use the `OPENAI_API_KEY` environment variable.
+- If you omit `base_url`, it will use the `OPENAI_API_ENDPOINT` environment variable (useful for custom endpoints like Azure/OpenAI-compatible proxies).
+- Precedence: values you pass explicitly to `OpenAIGateway(api_key=..., base_url=...)` always override environment variables.
+
+Examples:
+
+```python
+from mojentic.llm import LLMBroker
+from mojentic.llm.gateways import OpenAIGateway
+
+# 1) Easiest: rely on environment variables
+#    export OPENAI_API_KEY=sk-...
+#    export OPENAI_API_ENDPOINT=https://api.openai.com/v1   # optional
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway()  # picks up OPENAI_API_KEY/OPENAI_API_ENDPOINT automatically
+)
+
+# 2) Explicitly override one or both values
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway(api_key="your_key", base_url="https://api.openai.com/v1")
+)
+```
+
 ## 🤖 OpenAI Model Support
 
 The framework automatically handles parameter differences between model types, so you can switch between any models without code changes.
@@ -170,9 +201,9 @@ pip install -e ".[dev]"
 pytest
 ```
 
-## ⚠️ Project Status
+## ✅ Project Status
 
-While the Layer 1 API (LLMBroker, LLMGateway, tool use) has stabilized, the Layer 2 agentic capabilities are under heavy development and will likely change significantly.
+The agentic aspects of this framework are in the highest state of flux. The first layer has stabilized, as have the simpler parts of the second layer, and we're working on the stability of the asynchronous pubsub architecture. We expect Python 3.14 will be the real enabler for the async aspects of the second layer.
 
 ## 📄 License