Metadata-Version: 2.4
Name: smolagents-codex
Version: 0.1.0
Summary: Unofficial smolagents Model adapter for ChatGPT Codex OAuth device-code auth.
Author: smolagents-codex contributors
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: smolagents<2,>=1.26.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# smolagents-codex

*Use a ChatGPT/Codex OAuth session as a `smolagents.Model`.*

![Python](https://img.shields.io/badge/Python-%3E%3D3.10-3776ab?style=flat-square&logo=python&logoColor=white)
![smolagents](https://img.shields.io/badge/smolagents-%3E%3D1.26.0-111827?style=flat-square)
![Typed](https://img.shields.io/badge/types-py.typed-2563eb?style=flat-square)

[Getting Started](#getting-started) • [Python Usage](#python-usage) • [Support Matrix](#support-matrix) • [Troubleshooting](#troubleshooting)

</div>

---

`smolagents-codex` is an unofficial external adapter that lets
`smolagents.CodeAgent` call the ChatGPT Codex Responses backend through OAuth
device-code login.

It does not fork `smolagents`, does not use the Codex CLI, does not require a
Platform API key, and does not use LiteLLM or the OpenAI Python SDK.

> [!WARNING]
> This package talks to an internal ChatGPT/Codex transport, not the public
> OpenAI API. The backend can change without notice.

## Features

- `smolagents.Model` implementation for `CodeAgent`
- OAuth device-code login against ChatGPT/Codex
- Access-token refresh with local credential storage
- Direct HTTPS/SSE transport to the Codex Responses backend
- Text-only message conversion for system, developer, user, assistant, and
  CodeAgent observation history
- Client-side stop-sequence trimming

## Getting Started

Install the package in editable mode:

```shell
pip install -e '.[dev]'
```

Log in with device-code OAuth:

```shell
python -m smolagents_codex login
```

The command prints a verification URL and one-time code. Open the URL in a
normal browser and enter the code only if you started the login.

Check or clear credentials:

```shell
python -m smolagents_codex status
python -m smolagents_codex logout
```

> [!IMPORTANT]
> No default model is hardcoded. Pass a model ID that your ChatGPT/Codex
> account can use. Model IDs are case-sensitive.

## Python Usage

```python
from smolagents import CodeAgent
from smolagents_codex import CodexOAuthModel

model = CodexOAuthModel(model_id="MODEL_ID")

agent = CodeAgent(
    tools=[],
    model=model,
    stream_outputs=False,
    use_structured_outputs_internally=False,
    max_steps=3,
)

print(agent.run("Calculate 17 * 23 and return the result."))
```

Run the bundled example:

```shell
export SMOLAGENTS_CODEX_MODEL=MODEL_ID
python examples/code_agent.py

python examples/code_agent.py MODEL_ID
```

## Credentials

Set `SMOLAGENTS_CODEX_HOME` to choose the credential directory. Otherwise the
package uses `~/.smolagents-codex/credentials.json`.

Credential files are written with private Unix permissions where supported, but
file permissions are not encryption.

## Support Matrix

| Area | Status |
| --- | --- |
| `smolagents.CodeAgent` | Supported |
| Blocking `generate()` | Supported |
| Text messages | Supported |
| OAuth device-code login | Supported |
| Access-token refresh | Supported |
| Public smolagents streaming | Not supported |
| `ToolCallingAgent` / native function calls | Not supported |
| Structured `response_format` | Not supported |
| Images, audio, video, files | Not supported |
| Codex server-side tools | Not supported |
| Codex CLI state | Not used |

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Device auth disabled | Enable device-code authentication in ChatGPT security settings or ask a workspace admin. |
| `401` after refresh | Run `python -m smolagents_codex login`. |
| `403` | Check workspace membership, RBAC, entitlements, and admin restrictions. |
| `404` | Check the model ID and whether the endpoint is available to your plan. |
| `429` | You hit ChatGPT/Codex plan or usage limits. |
| Timeout | Retry on a stable network. |
| Corporate proxy/custom CA | Use standard `httpx` environment settings such as `HTTPS_PROXY`, `SSL_CERT_FILE`, or `SSL_CERT_DIR`. |
| Malformed credential file | Run `python -m smolagents_codex logout`, then `python -m smolagents_codex login`. |

## Development

```shell
ruff check .
mypy src/smolagents_codex
python -m build
```

Protocol details and upstream source commits are recorded in
[`PROTOCOL.md`](PROTOCOL.md). Re-check that file when Codex or `smolagents`
changes.
