codex-agent-framework 0.1.1__tar.gz

codex_agent_framework-0.1.1/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning where practical.
+## [0.1.1] - 2026-05-03
+### Fixed
+- Validate `ImageMessage` content before adding it to session state.
+- Prevent invalid or inaccessible observed images from polluting a session and breaking later SDK calls.
+
+### Tests
+- Add regression coverage for valid and invalid `ImageMessage` validation.
+- Verify `Agent.add_image()` rejects invalid images without appending a broken session message.
+
+
+## [0.1.0] - 2026-05-03
+
+### Added
+
+- Initial package metadata and console entry point.
+- Event-driven agent runtime, session persistence, tools, providers, commands, voice, image, and document extraction modules.
+- Test suite for core agent behavior, events, messages, image messages, utilities, and workers.

codex_agent_framework-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baptiste
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_agent_framework-0.1.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include codex_agent/prompts *.txt
+include codex_agent/get_text/default_gitignore
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

codex_agent_framework-0.1.1/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: codex-agent-framework
+Version: 0.1.1
+Summary: A lightweight event-driven Codex agent runtime.
+Author: Baptiste
+License-Expression: MIT
+Keywords: agent,ai,codex,openai,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4
+Requires-Dist: codex-backend-sdk
+Requires-Dist: filetype
+Requires-Dist: get-gecko-driver
+Requires-Dist: modict
+Requires-Dist: numpy
+Requires-Dist: odfpy
+Requires-Dist: openai
+Requires-Dist: openpyxl
+Requires-Dist: pathspec
+Requires-Dist: pillow
+Requires-Dist: prompt_toolkit
+Requires-Dist: pydub
+Requires-Dist: PyPDF2
+Requires-Dist: pynteract
+Requires-Dist: python-docx
+Requires-Dist: PyYAML
+Requires-Dist: regex
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: selenium
+Requires-Dist: tiktoken
+Requires-Dist: trafilatura
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: streamlit
+Requires-Dist: streamlit; extra == "streamlit"
+Dynamic: license-file
+
+# codex-agent
+
+`codex-agent-framework` is a lightweight Python runtime for building interactive, tool-using AI agents.
+
+It provides a reusable `Agent` abstraction with persistent sessions, local tools, slash commands, contextual providers, voice hooks, image handling, and document-reading helpers. The package can be used as a CLI assistant or embedded as a library in your own application.
+
+> Status: early alpha. APIs are still evolving.
+
+## Highlights
+
+- Interactive terminal agent exposed as `codex-agent`.
+- Persistent JSON sessions with `latest`, explicit session IDs, and session navigation commands.
+- Built-in local tools for reading, writing, editing, showing, observing, Bash, and Python execution.
+- Extensible tool, command, and provider decorators.
+- Event-driven internals for UI, streaming, voice, and automation integrations.
+- Document extraction helpers for folders, text files, URLs, PDFs, DOCX, XLSX, ODT, HTML, and more.
+- Optional image generation, image observation, voice, LaTeX, and Streamlit-oriented integration points.
+- Packaged prompt assets and runtime defaults.
+
+## Requirements
+
+- Python 3.10 or newer.
+- A working model backend configuration compatible with `codex-backend-sdk` / OpenAI usage.
+- Firefox / GeckoDriver may be needed for Selenium-backed web extraction paths.
+
+## Installation
+
+From a local checkout:
+
+```bash
+python -m pip install -e .
+```
+
+For development:
+
+```bash
+python -m pip install -e '.[dev]'
+```
+
+Optional Streamlit support:
+
+```bash
+python -m pip install -e '.[streamlit]'
+```
+
+## Quick start
+
+Run the bundled terminal assistant:
+
+```bash
+codex-agent
+```
+
+Or use the agent from Python:
+
+```python
+from codex_agent import Agent
+
+agent = Agent(
+    session="new",
+    username="Baptiste",
+    voice_enabled=False,
+)
+
+agent("Summarize this project in three bullet points.")
+```
+
+For an interactive Python-driven session:
+
+```python
+from codex_agent import Agent
+
+agent = Agent(session="latest", voice_enabled=False)
+agent.interact()
+```
+
+## Runtime directory and sessions
+
+By default, local runtime state is stored in:
+
+```text
+~/.agent_runtime
+```
+
+This directory contains, among other things:
+
+```text
+sessions/      persisted conversation histories as JSON
+workfolder/    generated or uploaded files
+tools/         user runtime tools
+providers/     user runtime context providers
+commands/      user runtime slash commands
+images/        generated or persisted image outputs
+```
+
+You can override the runtime location with:
+
+```bash
+AGENT_RUNTIME_DIR=/tmp/my-agent-runtime codex-agent
+```
+
+Session behavior:
+
+- `Agent(session="new")` starts a fresh session.
+- `Agent(session="latest")` resumes the newest saved session.
+- `Agent(session="<session_id>")` loads a specific saved session.
+- `Agent(session="/path/to/session.json")` loads a session file directly.
+
+Session IDs are timestamp-based and lexicographically sortable.
+
+## Built-in slash commands
+
+Inside the interactive agent, commands start with `/`.
+
+Common commands:
+
+```text
+/help                         list available commands
+/sessions                     list saved sessions
+/new_session                  create a new session
+/load_session latest          load latest session
+/load_session <session_id>    load a specific session
+/delete_session <session_id>  delete a session
+/next_session                 move to the next/newer session
+/previous_session             move to the previous/older session
+/compact                      compact completed history turns
+/config                       show model-related config
+/config model=gpt-test verbosity=low
+/model                        show current model
+/model gpt-test               update model
+/reasoning high               update reasoning effort
+/verbosity low                update verbosity
+```
+
+## Built-in tools
+
+The default agent registers local tools that can be exposed to the model:
+
+| Tool | Purpose |
+| --- | --- |
+| `read` | Extract text from files, folders, URLs, and common document formats. |
+| `write` | Write or overwrite one or more complete UTF-8 text files. |
+| `edit` | Apply exact-string replacements to local text files. |
+| `python` | Execute Python in a persistent interactive shell. |
+| `bash` | Execute shell commands. |
+| `observe` | Load an image into the conversation for visual analysis. |
+| `show` | Open a file, folder, or URL with the system default app/browser. |
+
+Use these with care: Bash, Python, write, and edit run with the current user's privileges.
+
+## Extending the agent
+
+### Define a tool
+
+```python
+from codex_agent import Agent, tool
+
+@tool
+def add(a: int, b: int) -> int:
+    """Return the sum of two integers."""
+    return a + b
+
+agent = Agent(session="new", voice_enabled=False)
+agent.add_tool(add)
+```
+
+### Define a slash command
+
+```python
+from codex_agent import Agent, command, get_agent
+
+@command
+def hello(name="world"):
+    return f"Hello, {name}! Current session: {get_agent().current_session_id}"
+
+agent = Agent(session="new", voice_enabled=False)
+agent.add_command(hello)
+print(agent("/hello Baptiste"))
+```
+
+### Define a context provider
+
+Providers inject ephemeral context into each model call. Their output is not persisted in the session.
+
+```python
+from codex_agent import Agent, provider
+
+@provider
+def app_context():
+    return "The user is working on the codex-agent repository."
+
+agent = Agent(session="new", voice_enabled=False)
+agent.add_provider(app_context)
+```
+
+### Runtime extensions
+
+The agent also loads Python modules from the runtime directory:
+
+```text
+~/.agent_runtime/tools/*.py
+~/.agent_runtime/providers/*.py
+~/.agent_runtime/commands/*.py
+```
+
+Decorated functions in those files are registered automatically when the agent starts.
+
+## Events
+
+`Agent` exposes an event bus for UI and automation integrations.
+
+Example:
+
+```python
+from codex_agent import Agent, MessageAddedEvent
+
+agent = Agent(session="new", voice_enabled=False)
+
+@agent.on(MessageAddedEvent)
+def log_message(event):
+    print(event.message.type)
+```
+
+Useful exported events include:
+
+- `MessageAddedEvent`
+- `ResponseStartEvent`
+- `ResponseContentDeltaEvent`
+- `ResponseDoneEvent`
+- `ToolCallStartEvent`
+- `ToolCallDoneEvent`
+- `AgentInterruptedEvent`
+- `AudioPlaybackEvent`
+
+## Configuration
+
+`Agent` accepts configuration through keyword arguments:
+
+```python
+agent = Agent(
+    session="latest",
+    model="gpt-5.4",
+    reasoning_effort="medium",
+    verbosity="medium",
+    input_token_limit=128000,
+    auto_compact=True,
+    web_search_enabled=False,
+    image_generation_enabled=False,
+    voice_enabled=False,
+)
+```
+
+Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers or slash commands.
+
+## Project layout
+
+```text
+codex_agent/                    Python package
+codex_agent/agent.py            Agent, AgentConfig, AgentSession
+codex_agent/builtin_tools.py    Built-in local tools
+codex_agent/builtin_commands.py Built-in slash commands
+codex_agent/builtin_providers.py Built-in context providers
+codex_agent/prompts/            Packaged prompt templates
+codex_agent/get_text/           Document extraction helpers
+tests/                          Test suite
+pyproject.toml                  Package metadata and build config
+MANIFEST.in                     Source distribution includes
+```
+
+## Testing
+
+Run the full suite:
+
+```bash
+python -m pytest
+```
+
+The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create or resume sessions from your real `~/.agent_runtime`.
+
+Current baseline:
+
+```text
+102 passed
+```
+
+## Packaging
+
+Build source and wheel distributions with:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+The distribution includes prompt text files and `codex_agent/get_text/default_gitignore` through package data and `MANIFEST.in`.
+
+## Recent changes
+- `0.1.1`: image observations are now validated before session persistence, preventing broken `ImageMessage` entries from poisoning later turns.
+
+## Safety notes
+
+This project is designed to let an AI assistant act on the local machine. That is powerful and potentially risky.
+
+Recommended practices:
+
+- Use a dedicated runtime directory for experiments.
+- Review tool calls before enabling autonomous workflows.
+- Avoid running the agent with elevated privileges.
+- Keep secrets out of prompts, logs, and committed runtime files.
+- Prefer temporary workfolders in tests and demos.
+
+## License
+
+MIT. See [LICENSE](LICENSE).