Metadata-Version: 2.4
Name: codex-agent-framework
Version: 0.1.2
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.2`: add `/clear` in the terminal chat to clear the screen without changing session history.
- `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).
