Metadata-Version: 2.4
Name: codex-chat-bot
Version: 0.1.4
Summary: A small single-session chat client for OpenAI-compatible Responses API endpoints.
Author-email: GGN_2015 <neko@jlulug.org>
Requires-Python: >=3.10
Requires-Dist: openai<3,>=1.99.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# codex-chat-bot

A small Python chat project with:

- a Python programming interface
- a command-line interface
- single-session memory
- configurable API key, base URL, model, and system rules

The project uses OpenAI SDK-compatible Responses API endpoints.

## Installation

```bash
python -m pip install codex-chat-bot
```

## Environment Variables

Only `CODEX_CHAT_*` environment variables are read:

```bash
export CODEX_CHAT_API_KEY="your API key"
export CODEX_CHAT_BASE_URL="https://api.openai.com/v1"
export CODEX_CHAT_MODEL="gpt-5.5"                       # optional
```

## JSON Config File

You can also load `api_key`, `base_url`, `model`, and `system_rules` from a
UTF-8 JSON file:

```json
{
    "api_key": "your API key",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-5.5",
    "system_rules": [
        "You are a concise programming assistant.",
        "Answer in English."
    ]
}
```

Use `--config` or `--config-file` to choose the file:

```bash
codex-chat --config ./config.json "Hello"
```

Values from the config file are used before environment variables and command
line options, so `CODEX_CHAT_*` variables and explicit flags can still override
the file for one run.

## Command-Line Usage

Run a single chat turn:

```bash
codex-chat "Write a Python hello world example."
```

Start interactive chat:

```bash
codex-chat
```

If `codex-chat` is not on your PATH, run the module directly:

```bash
python -m codex_chat_bot.cli
python -m codex_chat_bot.cli "Hello"
```

Interactive commands:

- `/name NAME` changes the name used for your next messages. The default name is `user`.
- `/reset` clears the current session memory.
- `/import PATH` loads chat history from a JSON file.
- `/export PATH` saves chat history to a JSON file.
- `/exit` or `/quit` exits the chat.

Common options:

```bash
codex-chat --api-key "your API key" --base-url "https://api.openai.com/v1" "Hello"
codex-chat --config ./config.json "Hello"
codex-chat --model gpt-5.5 --system "You are a concise programming assistant."
codex-chat --system-rule "Answer in English." --system-rule "Keep answers short." "Explain pytest."
codex-chat --system-rules-file ./rules.txt "Review this idea."
codex-chat --bind-history ./history.json "Continue our chat."
codex-chat --base-url "https://api.openai.com/v1" "Explain pytest."
```

If `CODEX_CHAT_API_KEY` or `CODEX_CHAT_BASE_URL` is not set and the value was
not passed on the command line, interactive CLI startup prompts for the missing
value.

`--bind-history` loads the JSON file if it already exists, creates an empty
history file if it does not, and writes every new message to that file as the
chat changes. If the file exists but is not valid chat history JSON, the CLI
prints a warning and recreates it as an empty history file.

## Python API

```python
from codex_chat_bot import ChatConfig, ChatSession

session = ChatSession(ChatConfig.from_env())

print(session.ask("Remember that my project is named codex-chat-bot."))
print(session.ask("What is my project called?"))
print(session.ask("This is Alice speaking.", username="alice"))

session.bind_history("history.json")
session.ask("This message is saved automatically.")
```

You can also pass configuration explicitly:

```python
from codex_chat_bot import ChatConfig, ChatSession

config = ChatConfig(
    api_key="your API key",
    base_url="https://api.openai.com/v1",
    model="gpt-5.5",
    system_rules=(
        "You are a patient Python programming assistant.",
        "Answer in English.",
        "Keep code examples runnable.",
    ),
)

session = ChatSession(config)
answer = session.ask("Write a function that reads a JSON file.")
print(answer)
```

`system_rules` are added to the session's initial system message and stay active
until the session is reset.

Pass `username=` to `ask()` or `send()` to distinguish different people in one
session. User messages are sent to the model with the speaker name included, and
chat history stores each message's `username`.

Chat history JSON uses a top-level `messages` array:

```json
{
    "messages": [
        { "role": "system", "content": "You are a helpful assistant.", "username": "system" },
        { "role": "user", "content": "Hello", "username": "alice" },
        { "role": "assistant", "content": "Hi!", "username": "assistant" }
    ]
}
```

## Tests

```bash
python -m pytest
```
