codex-agent-framework 0.1.1__py3-none-any.whl

codex_agent/ai.py

@@ -0,0 +1,494 @@
+import numpy as np
+from .message import AssistantMessage, MessageChunk
+from .utils import truncate
+from modict import modict
+import io, os
+from openai import OpenAI, OpenAIError
+from typing import Union, List
+from pydub import AudioSegment
+from .stream_utils import MappingStreamProcessor
+from .event import (
+    AgentInterrupted,
+    ResponseContentDeltaEvent,
+    ResponseDoneEvent,
+    ResponseMessageDeltaEvent,
+    ResponseOutputItemEvent,
+    ResponseReasoningDeltaEvent,
+    ResponseStartEvent,
+    ResponseToolCallsDeltaEvent,
+    ServerToolCallEvent,
+)
+from codex_backend_sdk import (
+    CodexClient,
+    OutputItem,
+    ResponseAborted,
+    ReasoningDelta,
+    ResponseFailed,
+    TextDelta,
+    ToolCall,
+)
+
+class ChunkStreamer(MappingStreamProcessor):
+    """Stream processor for AI response chunks, handling content, reasoning, and tool calls.
+
+    Args:
+        agent: The agent instance.
+        threaded: Whether to process streams in separate threads.
+    """
+
+    def __init__(self,agent, threaded=True):
+        self.agent=agent
+        super().__init__(
+            defaults=dict(content='',reasoning='',tool_calls=None,output_items=None),
+            processors=dict(content=self.agent.content_processors),
+            type=MessageChunk,
+            threaded=threaded
+        )
+
+
+class AIClientError(Exception):
+    """Base exception for AI client errors."""
+    pass
+
+class APIAuthenticationError(AIClientError):
+    """Exception raised for OpenAI API authentication failures."""
+    pass
+
+
+MAX_EMBEDDING_INPUT_TOKENS = 7500
+
+class AIClient:
+    """Client for Codex backend LLM calls and OpenAI voice/embedding calls."""
+
+    def __init__(self, agent):
+        """Initialize AI clients from agent config.
+
+        Args:
+            agent: The agent instance containing configuration and API key.
+        """
+        self.agent=agent
+        self._client = None
+        self._codex_client = None
+
+    @property
+    def client(self):
+        if self._client is None:
+            api_key=self.agent.config.get('openai_api_key') or os.getenv('OPENAI_API_KEY')
+            try:
+                self._client = OpenAI(api_key=api_key, timeout=180, max_retries=3)
+                if not self.api_key_is_valid():
+                    self._client=None
+                    raise APIAuthenticationError("Missing or invalid OpenAI API key. You can pass it when creating the agent with `agent=Agent(openai_api_key='your_api_key')` or via `agent.config.openai_api_key` or set the OPENAI_API_KEY environment variable. You can get an API key at https://platform.openai.com/account/api-keys.")
+            except OpenAIError:
+                self._client=None
+                raise APIAuthenticationError("Missing or invalid OpenAI API key. You can pass it when creating the agent with `agent=Agent(openai_api_key='your_api_key')` or via `agent.config.openai_api_key` or set the OPENAI_API_KEY environment variable. You can get an API key at https://platform.openai.com/account/api-keys.")
+        return self._client
+
+    @property
+    def codex_client(self):
+        """Client used for LLM calls through the ChatGPT Codex backend."""
+        if self._codex_client is None:
+            model = self.agent.config.get('model') or "gpt-5.4"
+            self._codex_client = CodexClient(model=model).authenticate()
+        return self._codex_client
+
+    def abort(self):
+        if self._codex_client is not None:
+            self._codex_client.abort()
+
+    def api_key_is_valid(self):
+        """
+        Verify that the API key is valid by making a minimal API call.
+
+        Returns:
+            bool: True if API key is valid, False otherwise
+        """
+        try:
+            # Make a minimal API call to verify the key
+            self.client.models.list()
+            return True
+        except Exception as e:
+            return False
+
+    def text_to_audio(self, model=None, voice=None, input='', voice_instructions='', **kwargs):
+        """
+        Generate speech audio from text using OpenAI TTS.
+
+        Args:
+            model: TTS model identifier (default: "gpt-4o-mini-tts")
+            voice: OpenAI-style voice name (alloy, echo, fable, onyx, nova, shimmer)
+            input: Text to synthesize
+            voice_instructions: Tone hint
+            **kwargs: Additional parameters
+
+        Returns:
+            BytesIO buffer containing MP3 audio
+        """
+        # Build TTS input
+        params = modict(
+            model=model or "gpt-4o-mini-tts",
+            voice=voice or "nova",
+            instructions=voice_instructions or "You speak with a friendly and casual tone.",
+            input=input
+        )
+
+        # Override with any additional kwargs
+        params.update(kwargs)
+
+        # Call OpenAI API
+        try:
+            mp3_buffer = io.BytesIO()
+
+            response = self.client.audio.speech.create(**params)
+
+            for chunk in response.iter_bytes():
+                mp3_buffer.write(chunk)
+
+            mp3_buffer.seek(0)
+
+            audio = AudioSegment.from_file(mp3_buffer,format="mp3").set_channels(1)
+
+            return audio
+
+        except Exception as e:
+            raise AIClientError(f"TTS generation failed: {str(e)}")
+
+    def audio_to_text(
+        self,
+        source: Union[str, io.BytesIO, bytes],
+        model: str = "whisper-1",
+        language: str = None,
+        prompt: str = None,
+        response_format: str = "text",
+        temperature: float = 0.0
+    ) -> str:
+        """
+        Convert audio to text using OpenAI's Whisper model.
+
+        Args:
+            source: Audio data as file_path string, BytesIO object or bytes
+            model: Model to use (default: "whisper-1")
+            language: ISO-639-1 language code (e.g., "en", "fr"). If None, language is auto-detected.
+            prompt: Optional text to guide the model's style
+            response_format: Format of output ("text", "json", "verbose_json", "srt", "vtt")
+            temperature: Sampling temperature between 0 and 1 (default: 0.0)
+
+        Returns:
+            Transcribed text as a string
+        """
+        if isinstance(source, str) and os.path.isfile(source):
+            with open(source, "rb") as f:
+                audio = io.BytesIO(f.read())
+        elif isinstance(source, bytes):
+                audio = io.BytesIO(source)
+        elif isinstance(source, io.BytesIO):
+            audio = source
+        else:
+            raise NotImplementedError(f"Unsupported audio source: {source}")
+
+        # Ensure the BytesIO object is at the start
+        audio.seek(0)
+
+        # Prepare the file for upload
+        audio.name = "audio.mp3"  # Add a name attribute
+
+        # Prepare transcription parameters
+        transcription_params = {
+            "model": model,
+            "file": audio,
+            "response_format": response_format,
+            "temperature": temperature
+        }
+
+        # Add optional parameters if provided
+        if language:
+            transcription_params["language"] = language
+        if prompt:
+            transcription_params["prompt"] = prompt
+
+        # Call OpenAI transcription API (retries handled by client)
+        try:
+            transcript = self.client.audio.transcriptions.create(**transcription_params)
+        except Exception as e:
+            raise AIClientError(f"Failed to transcribe audio: {str(e)}")
+
+        # Extract text from response
+        if response_format == "text":
+            return transcript
+        elif response_format in ["json", "verbose_json"]:
+            return transcript.text
+        else:
+            # For srt and vtt formats, return as-is
+            return transcript
+
+    def _stream_chunks(self, params):
+        params['tools'] = [
+            tool.to_response_tool() if hasattr(tool, "to_response_tool") else tool
+            for tool in params.get('tools') or []
+        ] or None
+
+        try:
+            stream_params = self._to_codex_stream_params(params)
+            response = self.codex_client.stream(
+                stream_params.pop('user_message'),
+                **stream_params
+            )
+        except Exception as e:
+            import traceback
+            import sys
+            print("\n[ERROR in ai.run setup]:", file=sys.stderr)
+            traceback.print_exc(file=sys.stderr)
+            yield MessageChunk(content=f"Hmmm, sorry! There was an error while calling the Codex backend client. Here is the error message I got:\n\n ```\n{str(e)}\n```")
+            return
+
+        try:
+            tool_call_index = 0
+            for event in response:
+                msg_chunk = self._codex_event_to_message_chunk(event, tool_call_index)
+                if msg_chunk and msg_chunk.get("tool_calls"):
+                    tool_call_index += 1
+                if msg_chunk:
+                    yield msg_chunk
+        except ResponseAborted:
+            raise AgentInterrupted()
+        except Exception as e:
+            yield MessageChunk(content=f"Hmmm, sorry! There was an error while reading the Codex backend stream. Here is the error message I got:\n\n ```\n{str(e)}\n```")
+
+    def _split_codex_messages(self, messages):
+        instructions = None
+        history = []
+        for msg in messages:
+            role = msg.get("role")
+            content = msg.get("content", "")
+            if role == "system" and instructions is None and isinstance(content, str):
+                instructions = content
+                continue
+            response_format = msg.to_response_format()
+            if response_format is None:
+                continue
+            if isinstance(response_format, list):
+                history.extend(response_format)
+            else:
+                history.append(response_format)
+        return instructions or "", history
+
+    def _to_codex_stream_params(self, params):
+        instructions, history = self._split_codex_messages(params.get("messages", []))
+        tools = params.get("tools") or []
+        reasoning = params.get("reasoning_effort")
+        model = params.get("model") or "gpt-5.4"
+        verbosity = params.get("verbosity")
+        return {
+            "user_message": None,
+            "conversation_history": history,
+            "instructions": instructions,
+            "model": model,
+            "verbosity": verbosity,
+            "tools": tools or None,
+            "tool_choice": "auto" if tools else "none",
+            "reasoning": reasoning,
+            "reasoning_summary": "auto" if reasoning else None,
+            "include_reasoning": bool(reasoning),
+        }
+
+    def _codex_event_to_message_chunk(self, event, tool_call_index=0):
+        if isinstance(event, TextDelta):
+            return MessageChunk(content=event.text)
+        if isinstance(event, ReasoningDelta):
+            return MessageChunk(reasoning=event.text)
+        if isinstance(event, ToolCall):
+            tool_call = modict({
+                "index": tool_call_index,
+                "type": "function_call",
+                "call_id": event.call_id,
+                "name": event.name,
+                "arguments": event.arguments,
+            })
+            return MessageChunk(tool_calls=[tool_call])
+        if isinstance(event, OutputItem):
+            item = modict(event.raw)
+            if item.get("type") == "custom_tool_call":
+                tool_call = modict({
+                    "index": tool_call_index,
+                    "type": "custom_tool_call",
+                    "call_id": item.get("call_id", ""),
+                    "name": item.get("name", ""),
+                    "input": item.get("input", ""),
+                })
+                return MessageChunk(tool_calls=[tool_call])
+            return MessageChunk(output_items=[item])
+        if isinstance(event, ResponseFailed):
+            return MessageChunk(content=f"Hmmm, sorry! The Codex backend returned an error:\n\n```\n[{event.code}] {event.message}\n```")
+        return None
+
+    def run(self, **params):
+        stream = ChunkStreamer(self.agent)(self._stream_chunks(params))
+        message = AssistantMessage(name=self.agent.config.get('name','assistant'))
+        content = ''
+        reasoning = ''
+
+        self.agent.emit(ResponseStartEvent, message=message)
+
+        try:
+            for chunk in stream:
+                self.agent.check_interrupt()
+                message.add_chunk(chunk)
+
+                if chunk.get('content'):
+                    content += chunk.content
+                    self.agent.emit(
+                        ResponseContentDeltaEvent,
+                        delta=chunk.content,
+                        content=content,
+                        chunk=chunk,
+                        message=message,
+                    )
+
+                if chunk.get('reasoning'):
+                    reasoning += chunk.reasoning
+                    self.agent.emit(
+                        ResponseReasoningDeltaEvent,
+                        delta=chunk.reasoning,
+                        reasoning=reasoning,
+                        chunk=chunk,
+                        message=message,
+                    )
+
+                if chunk.get('tool_calls'):
+                    self.agent.emit(
+                        ResponseToolCallsDeltaEvent,
+                        tool_calls=chunk.tool_calls,
+                        chunk=chunk,
+                        message=message,
+                    )
+
+                for item in chunk.get('output_items') or []:
+                    self.agent.emit(
+                        ResponseOutputItemEvent,
+                        item=item,
+                        chunk=chunk,
+                        message=message,
+                    )
+                    server_tool = self.agent.server_tool_for_item(item)
+                    if server_tool:
+                        self.agent.emit(
+                            ServerToolCallEvent,
+                            item=item,
+                            tool=server_tool,
+                            name=server_tool.type,
+                            call_id=item.get("call_id") or item.get("id") or server_tool.type,
+                            status=item.get("status", ""),
+                        )
+
+                self.agent.emit(ResponseMessageDeltaEvent, chunk=chunk, message=message)
+        except KeyboardInterrupt:
+            self.agent.interrupt("keyboard_interrupt")
+            raise AgentInterrupted()
+
+        self.agent.emit(ResponseDoneEvent, message=message)
+        return message
+
+    def _normalize(self, vect, precision=5):
+        """Normalize a vector and round to specified precision."""
+        inv_norm = 1.0 / np.linalg.norm(vect, ord=2)
+        return [round(x_i * inv_norm, precision) for x_i in vect]
+
+    def truncate_embedding_input(self, content):
+        return truncate(content, max_tokens=MAX_EMBEDDING_INPUT_TOKENS)
+
+    def embed_content(self, content: str, precision=5, dimensions=128, model="text-embedding-3-small"):
+        """
+        Embed a text string using OpenAI embeddings.
+
+        Args:
+            content: Text string to embed
+            precision: Number of decimal places for rounding (default: 5)
+            dimensions: Embedding dimensions (default: 128)
+            model: OpenAI embedding model to use (default: text-embedding-3-small)
+
+        Returns:
+            A normalized embedding vector
+        """
+        if not isinstance(content, str):
+            raise ValueError(f"Content must be a string, got {type(content)}")
+        content = self.truncate_embedding_input(content)
+
+        try:
+            response = self.client.embeddings.create(
+                model=model,
+                input=content,
+                dimensions=dimensions
+            )
+            embedding = response.data[0].embedding
+        except Exception as e:
+            raise AIClientError(f"Failed to generate embedding: {str(e)}")
+
+        return self._normalize(embedding, precision)
+
+    def embed_contents(self, contents: List[str], precision=5, dimensions=128, model="text-embedding-3-small"):
+        """
+        Embed multiple text strings using OpenAI embeddings.
+
+        Args:
+            contents: List of text strings to embed
+            precision: Number of decimal places for rounding (default: 5)
+            dimensions: Embedding dimensions (default: 128)
+            model: OpenAI embedding model to use (default: text-embedding-3-small)
+
+        Returns:
+            List of normalized embedding vectors
+
+        Note:
+            OpenAI API handles batching automatically for better performance.
+        """
+        if not all(isinstance(content, str) for content in contents):
+            raise ValueError("All contents must be strings")
+        contents = [self.truncate_embedding_input(content) for content in contents]
+
+        try:
+            response = self.client.embeddings.create(
+                model=model,
+                input=contents,
+                dimensions=dimensions
+            )
+            embeddings = [self._normalize(item.embedding, precision) for item in response.data]
+        except Exception as e:
+            raise AIClientError(f"Failed to generate embeddings: {str(e)}")
+
+        return embeddings
+
+    def similarity(self, emb1, emb2):
+        """
+        Calculate shifted positive cosine similarity between two embeddings.
+        Returns a score between 0 and 1.
+        """
+        return 0.5 + 0.5 * np.dot(np.array(emb1), np.array(emb2))
+
+    def embed_message(self, msg, precision=5, dimensions=128, model="text-embedding-3-small"):
+        """
+        Embed a Message object and assign the result to msg.embedding.
+
+        Args:
+            msg: Message object with text content
+            precision: Number of decimal places for rounding (default: 5)
+            dimensions: Embedding dimensions (default: 128)
+            model: OpenAI embedding model to use (default: text-embedding-3-small)
+
+        Returns:
+            The embedding vector (also assigned to msg.embedding)
+
+        Note:
+            Only text content is supported.
+        """
+        if hasattr(msg, 'content') and isinstance(msg.content, str):
+            content = msg.content
+        else:
+            raise ValueError("Message must have text content")
+
+        # Generate embedding
+        embedding = self.embed_content(content, precision, dimensions, model)
+
+        # Assign to msg.embedding
+        msg.embedding = embedding
+
+        return embedding

codex_agent/builtin_commands.py

@@ -0,0 +1,136 @@
+"""Built-in slash commands."""
+
+from .command import command
+from .tool import get_agent
+
+
+MODEL_CONFIG_KEYS = (
+    "model",
+    "reasoning_effort",
+    "verbosity",
+    "input_token_limit",
+    "max_input_tokens",
+    "auto_compact",
+)
+
+
+def parse_config_value(value):
+    if isinstance(value, bool):
+        return value
+    if not isinstance(value, str):
+        return value
+
+    lowered = value.lower()
+    if lowered in ("true", "yes", "on", "1"):
+        return True
+    if lowered in ("false", "no", "off", "0"):
+        return False
+    if value.isdigit():
+        return int(value)
+    return value
+
+
+def format_model_config(agent):
+    return "\n".join(f"{key}: {agent.config.get(key)!r}" for key in MODEL_CONFIG_KEYS)
+
+
+def update_model_config(**values):
+    agent = get_agent()
+    updates = {key: parse_config_value(value) for key, value in values.items()}
+    unknown = sorted(key for key in updates if key not in MODEL_CONFIG_KEYS)
+    if unknown:
+        raise ValueError(f"Unknown model config keys: {', '.join(unknown)}")
+    agent.update_config(updates)
+    changed = ", ".join(f"{key}={agent.config.get(key)!r}" for key in updates)
+    return f"Updated config: {changed}" if changed else format_model_config(agent)
+
+
+@command
+def help():
+    agent = get_agent()
+    names = ", ".join(f"/{name}" for name in sorted(agent.commands))
+    return f"Available commands: {names}"
+
+
+@command
+def compact():
+    agent = get_agent()
+    message = agent.session.compact(
+        model=agent.config.model,
+        instructions=agent.get_system_message().content,
+    )
+    if message is None:
+        return "Nothing to compact."
+    return f"Compacted {message.compacted_message_count} messages."
+
+
+@command
+def sessions():
+    agent = get_agent()
+    session_ids = agent.get_sessions()
+    if not session_ids:
+        return "No saved sessions."
+    lines = []
+    for session_id in session_ids:
+        prefix = "* " if session_id == agent.current_session_id else "  "
+        lines.append(f"{prefix}{session_id}")
+    return "\n".join(lines)
+
+
+@command
+def new_session():
+    agent = get_agent()
+    session = agent.start_new_session()
+    return f"Created session: {session.session_id}"
+
+
+@command
+def load_session(session_id="latest"):
+    agent = get_agent()
+    session = agent.load_session(session_id)
+    return f"Loaded session: {session.session_id}"
+
+
+@command
+def delete_session(session_id):
+    agent = get_agent()
+    deleted_id = agent.delete_session(session_id)
+    return f"Deleted session: {deleted_id}"
+
+
+@command
+def next_session():
+    session = get_agent().navigate_session("next")
+    return f"Loaded session: {session.session_id}"
+
+
+@command
+def previous_session():
+    session = get_agent().navigate_session("previous")
+    return f"Loaded session: {session.session_id}"
+
+
+@command
+def config(**values):
+    return update_model_config(**values)
+
+
+@command
+def model(value=None):
+    if value is None:
+        return f"model: {get_agent().config.model!r}"
+    return update_model_config(model=value)
+
+
+@command
+def reasoning(value=None):
+    if value is None:
+        return f"reasoning_effort: {get_agent().config.reasoning_effort!r}"
+    return update_model_config(reasoning_effort=value)
+
+
+@command
+def verbosity(value=None):
+    if value is None:
+        return f"verbosity: {get_agent().config.verbosity!r}"
+    return update_model_config(verbosity=value)

codex_agent/builtin_providers.py

@@ -0,0 +1,42 @@
+"""Built-in ephemeral context providers."""
+
+from datetime import datetime
+import os
+
+from .memory import format_memory_results_xml
+from .provider import provider
+from .tool import get_agent
+
+
+@provider
+def date_and_time():
+    now = datetime.now().astimezone()
+    return f"Current date and time: {now.strftime('%Y-%m-%d %H:%M:%S %Z%z')}"
+
+
+@provider
+def cwd():
+    return f"Current working directory: {os.getcwd()}"
+
+
+@provider
+def retrieved_memory():
+    agent = get_agent()
+    if not agent.memory.messages:
+        return None
+
+    context = [
+        msg for msg in agent.session.context_messages()
+        if agent.is_message_visible_in_context(msg)
+    ]
+    if not context:
+        return None
+
+    results = agent.memory.retrieve(
+        context,
+        max_tokens=agent.config.max_memory_tokens,
+        until=agent.memory_retrieval_until_timestamp(),
+    )
+    if not results:
+        return None
+    return format_memory_results_xml(results, root="retrieved_memories")