codex-chat-bot 0.1.0__tar.gz

codex_chat_bot-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Local secrets and environment files
+.env
+.env.*
+!.env.example
+
+# IDE and OS files
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

codex_chat_bot-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: codex-chat-bot
+Version: 0.1.0
+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
+```
+
+## 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:
+
+- `/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 --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 it if it does
+not, and writes every new message to that file as the chat changes.
+
+## 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?"))
+
+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.
+
+Chat history JSON uses a top-level `messages` array:
+
+```json
+{
+    "messages": [
+        { "role": "system", "content": "You are a helpful assistant." },
+        { "role": "user", "content": "Hello" },
+        { "role": "assistant", "content": "Hi!" }
+    ]
+}
+```
+
+## Tests
+
+```bash
+python -m pytest
+```

codex_chat_bot-0.1.0/README.md

@@ -0,0 +1,128 @@
+# 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
+```
+
+## 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:
+
+- `/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 --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 it if it does
+not, and writes every new message to that file as the chat changes.
+
+## 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?"))
+
+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.
+
+Chat history JSON uses a top-level `messages` array:
+
+```json
+{
+    "messages": [
+        { "role": "system", "content": "You are a helpful assistant." },
+        { "role": "user", "content": "Hello" },
+        { "role": "assistant", "content": "Hi!" }
+    ]
+}
+```
+
+## Tests
+
+```bash
+python -m pytest
+```

codex_chat_bot-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-chat-bot"
+version = "0.1.0"
+description = "A small single-session chat client for OpenAI-compatible Responses API endpoints."
+readme = "README.md"
+authors = [
+  { name = "GGN_2015", email = "neko@jlulug.org" },
+]
+requires-python = ">=3.10"
+dependencies = [
+  "openai>=1.99.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+codex-chat = "codex_chat_bot.cli:main"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]

codex_chat_bot-0.1.0/src/codex_chat_bot/__init__.py

@@ -0,0 +1,19 @@
+"""Single-session chat helpers for OpenAI-compatible Responses API clients."""
+
+from .config import ChatConfig
+from .errors import ChatBotError, MissingAPIKeyError, MissingBaseURLError, ResponseTextError
+from .session import ChatResponse, ChatSession, Message
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ChatBotError",
+    "ChatConfig",
+    "ChatResponse",
+    "ChatSession",
+    "Message",
+    "MissingAPIKeyError",
+    "MissingBaseURLError",
+    "ResponseTextError",
+    "__version__",
+]

codex_chat_bot-0.1.0/src/codex_chat_bot/cli.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+from collections.abc import Sequence
+from dataclasses import replace
+from pathlib import Path
+
+from . import __version__
+from .config import ChatConfig
+from .errors import ChatBotError
+from .session import ChatSession
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codex-chat",
+        description="A simple single-session chat CLI for OpenAI-compatible endpoints.",
+    )
+    parser.add_argument(
+        "message",
+        nargs="*",
+        help="Run one chat turn and print the answer. Omit to start interactive mode.",
+    )
+    parser.add_argument("--api-key", help="API key. Defaults to CODEX_CHAT_API_KEY.")
+    parser.add_argument("--base-url", help="API base URL. Defaults to CODEX_CHAT_BASE_URL.")
+    parser.add_argument("--model", help="Model name. Defaults to CODEX_CHAT_MODEL or gpt-5.5.")
+    parser.add_argument(
+        "--system",
+        dest="system_rules",
+        action="append",
+        help="System instruction for this session. Repeat the option to add multiple instructions.",
+    )
+    parser.add_argument(
+        "--system-rule",
+        action="append",
+        dest="system_rules",
+        help="System rule for this session. Repeat the option to add multiple rules.",
+    )
+    parser.add_argument(
+        "--system-rules-file",
+        help="Read system rules from a UTF-8 text file, one non-empty line per rule.",
+    )
+    parser.add_argument("--temperature", type=float, help="Optional model temperature.")
+    parser.add_argument("--max-output-tokens", type=int, help="Optional response token limit.")
+    parser.add_argument(
+        "--max-history-messages",
+        type=int,
+        help="Keep only the latest N non-system messages in memory.",
+    )
+    parser.add_argument("--import-history", help="Load chat history from a JSON file before chatting.")
+    parser.add_argument("--bind-history", help="Bind chat history to a JSON file and save every update.")
+    parser.add_argument(
+        "--export-history",
+        nargs="?",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument("--version", action="store_true", help="Print package version and exit.")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(__version__)
+        return 0
+    if args.export_history:
+        parser.error("--export-history was renamed to --bind-history")
+
+    try:
+        system_rules = _collect_system_rules(args.system_rules, args.system_rules_file)
+        config = ChatConfig.from_env(
+            api_key=args.api_key,
+            base_url=args.base_url,
+            model=args.model,
+            system_rules=system_rules,
+            temperature=args.temperature,
+            max_output_tokens=args.max_output_tokens,
+            max_history_messages=args.max_history_messages,
+        )
+        config = _prompt_for_missing_required_config(config)
+        session = ChatSession(config)
+        if args.bind_history:
+            session.bind_history(args.bind_history)
+        elif args.import_history:
+            session.load_history(args.import_history)
+    except (ChatBotError, OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    return _run_session(session, args.message)
+
+
+def _run_session(session: ChatSession, message_parts: list[str]) -> int:
+    try:
+        if message_parts:
+            return _run_one_shot(session, " ".join(message_parts))
+        return _run_interactive(session)
+    except KeyboardInterrupt:
+        print()
+        return 130
+
+
+def _run_one_shot(session: ChatSession, message: str) -> int:
+    try:
+        print(session.ask(message))
+        return 0
+    except ChatBotError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _run_interactive(session: ChatSession) -> int:
+    print("Codex Chat Bot")
+    print("Commands: /reset clears this session, /import PATH loads history, /export PATH saves history, /exit quits.")
+
+    while True:
+        try:
+            user_text = input("you> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+
+        if not user_text:
+            continue
+        if user_text in {"/exit", "/quit"}:
+            return 0
+        if user_text == "/reset":
+            session.reset()
+            print("session reset")
+            continue
+        if user_text.startswith("/import "):
+            _run_import_command(session, user_text.removeprefix("/import ").strip())
+            continue
+        if user_text.startswith("/export "):
+            _run_export_command(session, user_text.removeprefix("/export ").strip())
+            continue
+
+        try:
+            answer = session.ask(user_text)
+        except ChatBotError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            continue
+
+        print(f"assistant> {answer}")
+
+
+def _run_import_command(session: ChatSession, path: str) -> None:
+    if not path:
+        print("usage: /import PATH")
+        return
+
+    try:
+        session.load_history(path)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return
+
+    print(f"history imported from {path}")
+
+
+def _run_export_command(session: ChatSession, path: str) -> None:
+    if not path:
+        print("usage: /export PATH")
+        return
+
+    try:
+        session.save_history(path)
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return
+
+    print(f"history exported to {path}")
+
+
+def _collect_system_rules(rules: list[str] | None, rules_file: str | None) -> list[str] | None:
+    collected: list[str] = []
+    if rules_file:
+        collected.extend(line.strip() for line in Path(rules_file).read_text(encoding="utf-8").splitlines())
+    if rules:
+        collected.extend(rules)
+
+    clean_rules = [rule.strip() for rule in collected if rule.strip()]
+    return clean_rules or None
+
+
+def _prompt_for_missing_required_config(config: ChatConfig) -> ChatConfig:
+    api_key = _clean_optional_text(config.api_key)
+    base_url = _clean_optional_text(config.base_url)
+    if api_key and base_url:
+        return replace(config, api_key=api_key, base_url=base_url)
+
+    if not _is_interactive_input():
+        return replace(config, api_key=api_key, base_url=base_url)
+
+    prompted_api_key = api_key
+    prompted_base_url = base_url
+
+    try:
+        if not prompted_api_key:
+            print("No API key found in --api-key or CODEX_CHAT_API_KEY.", file=sys.stderr)
+            prompted_api_key = getpass.getpass("API key: ")
+        if not prompted_base_url:
+            print("No API base URL found in --base-url or CODEX_CHAT_BASE_URL.", file=sys.stderr)
+            prompted_base_url = input("Base URL: ")
+    except (EOFError, KeyboardInterrupt):
+        print(file=sys.stderr)
+        return replace(config, api_key=_clean_optional_text(prompted_api_key), base_url=_clean_optional_text(prompted_base_url))
+
+    return replace(
+        config,
+        api_key=_clean_optional_text(prompted_api_key),
+        base_url=_clean_optional_text(prompted_base_url),
+    )
+
+
+def _clean_optional_text(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def _is_interactive_input() -> bool:
+    return sys.stdin.isatty()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_chat_bot-0.1.0/src/codex_chat_bot/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+DEFAULT_MODEL = "gpt-5.5"
+DEFAULT_SYSTEM_RULES = ("You are a helpful assistant.",)
+
+
+@dataclass(frozen=True)
+class ChatConfig:
+    """Runtime configuration for a chat session."""
+
+    api_key: str | None = None
+    base_url: str | None = None
+    model: str = DEFAULT_MODEL
+    system_rules: tuple[str, ...] = DEFAULT_SYSTEM_RULES
+    temperature: float | None = None
+    max_output_tokens: int | None = None
+    max_history_messages: int | None = None
+    timeout: float | None = None
+    organization: str | None = None
+    project: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "system_rules", _normalize_system_rules(self.system_rules))
+
+    @classmethod
+    def from_env(cls, **overrides: object) -> "ChatConfig":
+        values: dict[str, object] = {
+            "api_key": _first_env("CODEX_CHAT_API_KEY"),
+            "base_url": _first_env("CODEX_CHAT_BASE_URL"),
+            "model": _first_env("CODEX_CHAT_MODEL") or DEFAULT_MODEL,
+            "temperature": _optional_float(_first_env("CODEX_CHAT_TEMPERATURE")),
+            "max_output_tokens": _optional_int(_first_env("CODEX_CHAT_MAX_OUTPUT_TOKENS")),
+            "max_history_messages": _optional_int(_first_env("CODEX_CHAT_MAX_HISTORY_MESSAGES")),
+            "timeout": _optional_float(_first_env("CODEX_CHAT_TIMEOUT")),
+            "organization": _first_env("CODEX_CHAT_ORG_ID"),
+            "project": _first_env("CODEX_CHAT_PROJECT_ID"),
+        }
+
+        for key, value in overrides.items():
+            if value is not None:
+                values[key] = value
+
+        return cls(**values)
+
+
+def _first_env(*names: str) -> str | None:
+    for name in names:
+        value = os.getenv(name)
+        if value:
+            return value
+    return None
+
+
+def _optional_int(value: str | None) -> int | None:
+    if value is None:
+        return None
+    return int(value)
+
+
+def _optional_float(value: str | None) -> float | None:
+    if value is None:
+        return None
+    return float(value)
+
+
+def _normalize_system_rules(value: object) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return tuple(line.strip() for line in value.splitlines() if line.strip())
+    if isinstance(value, Sequence):
+        return tuple(str(item).strip() for item in value if str(item).strip())
+    raise TypeError("system_rules must be a string, a sequence of strings, or None.")

codex_chat_bot-0.1.0/src/codex_chat_bot/errors.py

@@ -0,0 +1,14 @@
+class ChatBotError(Exception):
+    """Base exception for codex-chat-bot."""
+
+
+class MissingAPIKeyError(ChatBotError):
+    """Raised when no API key is available."""
+
+
+class MissingBaseURLError(ChatBotError):
+    """Raised when no API base URL is available."""
+
+
+class ResponseTextError(ChatBotError):
+    """Raised when response text cannot be extracted from an API response."""

codex_chat_bot-0.1.0/src/codex_chat_bot/session.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .config import ChatConfig
+from .errors import MissingAPIKeyError, MissingBaseURLError, ResponseTextError
+
+
+Role = Literal["system", "developer", "user", "assistant"]
+
+
+@dataclass(frozen=True)
+class Message:
+    role: Role
+    content: str
+
+    def to_api(self) -> dict[str, str]:
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass(frozen=True)
+class ChatResponse:
+    text: str
+    raw: Any
+    messages: tuple[Message, ...]
+
+
+class ChatSession:
+    """Single-session chat state kept entirely in local memory."""
+
+    def __init__(self, config: ChatConfig | None = None, client: Any | None = None) -> None:
+        self.config = config or ChatConfig.from_env()
+        self._client = client or self._build_client()
+        self._messages: list[Message] = []
+        self._history_path: Path | None = None
+        self.reset()
+
+    @property
+    def messages(self) -> tuple[Message, ...]:
+        return tuple(self._messages)
+
+    def export_history_json(self) -> str:
+        payload = {"messages": [message.to_api() for message in self._messages]}
+        return json.dumps(payload, ensure_ascii=False, indent=4)
+
+    def save_history(self, path: str | Path) -> None:
+        Path(path).write_text(self.export_history_json() + "\n", encoding="utf-8")
+
+    def bind_history(self, path: str | Path) -> None:
+        history_path = Path(path)
+        previous_history_path = self._history_path
+        self._history_path = None
+        if history_path.exists():
+            try:
+                self.load_history(history_path)
+            except Exception:
+                self._history_path = previous_history_path
+                raise
+
+        self._history_path = history_path
+        self._save_bound_history()
+
+    def load_history_json(self, data: str) -> None:
+        try:
+            payload = json.loads(data)
+        except json.JSONDecodeError as exc:
+            raise ValueError("chat history must be valid JSON") from exc
+
+        messages = _messages_from_history_payload(payload)
+        self._messages = list(messages)
+        self._trim_history()
+        self._save_bound_history()
+
+    def load_history(self, path: str | Path) -> None:
+        self.load_history_json(Path(path).read_text(encoding="utf-8"))
+
+    def reset(self, system_rules: Sequence[str] | None = None) -> None:
+        self._messages.clear()
+        system_content = self._build_system_content(system_rules)
+        if system_content:
+            self._messages.append(Message(role="system", content=system_content))
+        self._save_bound_history()
+
+    def ask(self, message: str, **extra_request_args: Any) -> str:
+        return self.send(message, **extra_request_args).text
+
+    def send(self, message: str, **extra_request_args: Any) -> ChatResponse:
+        message = message.strip()
+        if not message:
+            raise ValueError("message cannot be empty")
+
+        self._messages.append(Message(role="user", content=message))
+        try:
+            response = self._client.responses.create(**self._request_payload(extra_request_args))
+        except Exception:
+            self._messages.pop()
+            self._save_bound_history()
+            raise
+
+        text = _extract_response_text(response)
+        self._messages.append(Message(role="assistant", content=text))
+        self._trim_history()
+        self._save_bound_history()
+        return ChatResponse(text=text, raw=response, messages=self.messages)
+
+    def _request_payload(self, extra_request_args: Mapping[str, Any]) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "model": self.config.model,
+            "input": [message.to_api() for message in self._messages],
+        }
+        if self.config.temperature is not None:
+            payload["temperature"] = self.config.temperature
+        if self.config.max_output_tokens is not None:
+            payload["max_output_tokens"] = self.config.max_output_tokens
+
+        payload.update(extra_request_args)
+        return payload
+
+    def _build_system_content(self, system_rules: Sequence[str] | None) -> str:
+        rules = self.config.system_rules if system_rules is None else system_rules
+
+        clean_rules = [str(rule).strip() for rule in rules if str(rule).strip()]
+        return "\n".join(clean_rules)
+
+    def _trim_history(self) -> None:
+        max_messages = self.config.max_history_messages
+        if max_messages is None or max_messages <= 0:
+            return
+
+        prefix: list[Message] = []
+        rest = self._messages
+        while rest and rest[0].role in {"system", "developer"}:
+            prefix.append(rest[0])
+            rest = rest[1:]
+
+        if len(rest) > max_messages:
+            rest = rest[-max_messages:]
+        self._messages = prefix + rest
+
+    def _save_bound_history(self) -> None:
+        if self._history_path is not None:
+            self.save_history(self._history_path)
+
+    def _build_client(self) -> Any:
+        if not self.config.api_key:
+            raise MissingAPIKeyError(
+                "missing API key; set CODEX_CHAT_API_KEY, pass --api-key, "
+                "or pass ChatConfig(api_key=...)."
+            )
+        if not self.config.base_url:
+            raise MissingBaseURLError(
+                "missing API base URL; set CODEX_CHAT_BASE_URL, pass --base-url, "
+                "or pass ChatConfig(base_url=...)."
+            )
+
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise RuntimeError("openai package is required; run `pip install -e .`.") from exc
+
+        kwargs: dict[str, Any] = {"api_key": self.config.api_key, "base_url": self.config.base_url}
+        for name in ("timeout", "organization", "project"):
+            value = getattr(self.config, name)
+            if value is not None:
+                kwargs[name] = value
+
+        return OpenAI(**kwargs)
+
+
+def _extract_response_text(response: Any) -> str:
+    output_text = _get_value(response, "output_text")
+    if isinstance(output_text, str):
+        return output_text
+
+    chunks: list[str] = []
+    for item in _get_value(response, "output", default=[]) or []:
+        for part in _get_value(item, "content", default=[]) or []:
+            text = _get_value(part, "text")
+            if isinstance(text, str):
+                chunks.append(text)
+
+    if chunks:
+        return "".join(chunks)
+
+    raise ResponseTextError("could not extract text from the model response")
+
+
+def _messages_from_history_payload(payload: Any) -> tuple[Message, ...]:
+    if isinstance(payload, list):
+        raw_messages = payload
+    elif isinstance(payload, Mapping) and isinstance(payload.get("messages"), list):
+        raw_messages = payload["messages"]
+    else:
+        raise ValueError("chat history JSON must be an object with a messages array")
+
+    messages: list[Message] = []
+    for index, item in enumerate(raw_messages):
+        if not isinstance(item, Mapping):
+            raise ValueError(f"chat history message {index} must be an object")
+
+        role = item.get("role")
+        content = item.get("content")
+        if role not in {"system", "developer", "user", "assistant"}:
+            raise ValueError(f"chat history message {index} has an invalid role")
+        if not isinstance(content, str):
+            raise ValueError(f"chat history message {index} content must be a string")
+
+        messages.append(Message(role=role, content=content))
+
+    return tuple(messages)
+
+
+def _get_value(obj: Any, key: str, default: Any = None) -> Any:
+    if isinstance(obj, Mapping):
+        return obj.get(key, default)
+    return getattr(obj, key, default)

codex_chat_bot-0.1.0/tests/test_cli.py

@@ -0,0 +1,169 @@
+import pytest
+
+from codex_chat_bot import ChatConfig
+from codex_chat_bot.cli import build_parser, main
+from codex_chat_bot.cli import _collect_system_rules
+from codex_chat_bot.cli import _prompt_for_missing_required_config
+
+
+class FakeSession:
+    instances = []
+
+    def __init__(self, config):
+        self.config = config
+        self.bound_paths = []
+        self.imported_paths = []
+        self.exported_paths = []
+        self.asked_messages = []
+        FakeSession.instances.append(self)
+
+    def ask(self, message):
+        self.asked_messages.append(message)
+        return f"answer: {message}"
+
+    def bind_history(self, path):
+        self.bound_paths.append(path)
+
+    def load_history(self, path):
+        self.imported_paths.append(path)
+
+    def save_history(self, path):
+        self.exported_paths.append(path)
+
+
+class InterruptingSession(FakeSession):
+    def ask(self, message):
+        self.asked_messages.append(message)
+        raise KeyboardInterrupt
+
+
+def test_cli_reports_missing_api_key_without_traceback(monkeypatch, capsys):
+    monkeypatch.delenv("CODEX_CHAT_API_KEY", raising=False)
+    monkeypatch.delenv("CODEX_CHAT_BASE_URL", raising=False)
+    monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+
+    status = main(["--base-url", "https://api.example/v1", "hello"])
+
+    captured = capsys.readouterr()
+    assert status == 1
+    assert "missing API key" in captured.err
+    assert "Traceback" not in captured.err
+
+
+def test_cli_reports_missing_base_url_without_traceback(monkeypatch, capsys):
+    monkeypatch.delenv("CODEX_CHAT_API_KEY", raising=False)
+    monkeypatch.delenv("CODEX_CHAT_BASE_URL", raising=False)
+    monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+
+    status = main(["--api-key", "test-key", "hello"])
+
+    captured = capsys.readouterr()
+    assert status == 1
+    assert "missing API base URL" in captured.err
+    assert "Traceback" not in captured.err
+
+
+def test_prompt_for_missing_required_config(monkeypatch, capsys):
+    monkeypatch.setattr("sys.stdin.isatty", lambda: True)
+    monkeypatch.setattr("getpass.getpass", lambda prompt: " prompted-key ")
+    monkeypatch.setattr("builtins.input", lambda prompt: " https://api.example/v1 ")
+
+    config = _prompt_for_missing_required_config(ChatConfig())
+
+    captured = capsys.readouterr()
+    assert config.api_key == "prompted-key"
+    assert config.base_url == "https://api.example/v1"
+    assert "No API key found" in captured.err
+    assert "No API base URL found" in captured.err
+
+
+def test_collect_system_rules_from_file_and_flags(tmp_path):
+    rules_file = tmp_path / "rules.txt"
+    rules_file.write_text("Answer in English.\n\nKeep answers short.\n", encoding="utf-8")
+
+    rules = _collect_system_rules(["Use Markdown."], str(rules_file))
+
+    assert rules == ["Answer in English.", "Keep answers short.", "Use Markdown."]
+
+
+def test_system_and_system_rule_share_system_rules_argument():
+    args = build_parser().parse_args(
+        [
+            "--system",
+            "You are a concise programming assistant.",
+            "--system-rule",
+            "Answer in English.",
+            "hello",
+        ]
+    )
+
+    assert args.system_rules == ["You are a concise programming assistant.", "Answer in English."]
+
+
+def test_history_options_are_parsed():
+    args = build_parser().parse_args(
+        [
+            "--import-history",
+            "in.json",
+            "--bind-history",
+            "bound.json",
+            "hello",
+        ]
+    )
+
+    assert args.import_history == "in.json"
+    assert args.bind_history == "bound.json"
+
+
+def test_export_history_option_reports_rename(capsys):
+    with pytest.raises(SystemExit) as exc_info:
+        main(["--export-history", "out.json"])
+
+    captured = capsys.readouterr()
+    assert exc_info.value.code == 2
+    assert "--export-history was renamed to --bind-history" in captured.err
+
+
+def test_cli_binds_history(monkeypatch, capsys):
+    FakeSession.instances.clear()
+    monkeypatch.setenv("CODEX_CHAT_API_KEY", "test-key")
+    monkeypatch.setenv("CODEX_CHAT_BASE_URL", "https://api.example/v1")
+    monkeypatch.setattr("codex_chat_bot.cli.ChatSession", FakeSession)
+
+    status = main(["--bind-history", "history.json", "hello"])
+
+    captured = capsys.readouterr()
+    session = FakeSession.instances[0]
+    assert status == 0
+    assert session.bound_paths == ["history.json"]
+    assert session.imported_paths == []
+    assert session.exported_paths == []
+    assert session.asked_messages == ["hello"]
+    assert captured.out == "answer: hello\n"
+
+
+def test_cli_does_not_skip_bound_history_on_keyboard_interrupt_in_one_shot(monkeypatch, capsys):
+    InterruptingSession.instances.clear()
+    monkeypatch.setenv("CODEX_CHAT_API_KEY", "test-key")
+    monkeypatch.setenv("CODEX_CHAT_BASE_URL", "https://api.example/v1")
+    monkeypatch.setattr("codex_chat_bot.cli.ChatSession", InterruptingSession)
+
+    status = main(["--bind-history", "history.json", "hello"])
+
+    session = InterruptingSession.instances[0]
+    assert status == 130
+    assert session.bound_paths == ["history.json"]
+
+
+def test_cli_binds_history_before_keyboard_interrupt_in_interactive(monkeypatch, capsys):
+    FakeSession.instances.clear()
+    monkeypatch.setenv("CODEX_CHAT_API_KEY", "test-key")
+    monkeypatch.setenv("CODEX_CHAT_BASE_URL", "https://api.example/v1")
+    monkeypatch.setattr("codex_chat_bot.cli.ChatSession", FakeSession)
+    monkeypatch.setattr("builtins.input", lambda prompt: (_ for _ in ()).throw(KeyboardInterrupt))
+
+    status = main(["--bind-history", "history.json"])
+
+    session = FakeSession.instances[0]
+    assert status == 0
+    assert session.bound_paths == ["history.json"]

codex_chat_bot-0.1.0/tests/test_config.py

@@ -0,0 +1,56 @@
+from codex_chat_bot import ChatConfig
+from codex_chat_bot.config import DEFAULT_MODEL, DEFAULT_SYSTEM_RULES
+
+
+def test_config_reads_codex_chat_environment(monkeypatch):
+    monkeypatch.setenv("OPENAI_API_KEY", "openai-key")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://ignored.example/v1")
+    monkeypatch.setenv("OPENAI_MODEL", "ignored-model")
+    monkeypatch.setenv("CODEX_CHAT_API_KEY", "codex-key")
+    monkeypatch.setenv("CODEX_CHAT_BASE_URL", "https://api.example/v1")
+    monkeypatch.setenv("CODEX_CHAT_MODEL", "codex-model")
+
+    config = ChatConfig.from_env()
+
+    assert config.api_key == "codex-key"
+    assert config.base_url == "https://api.example/v1"
+    assert config.model == "codex-model"
+
+
+def test_config_ignores_openai_environment(monkeypatch):
+    monkeypatch.delenv("CODEX_CHAT_API_KEY", raising=False)
+    monkeypatch.delenv("CODEX_CHAT_BASE_URL", raising=False)
+    monkeypatch.delenv("CODEX_CHAT_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_API_KEY", "openai-key")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://ignored.example/v1")
+    monkeypatch.setenv("OPENAI_MODEL", "ignored-model")
+
+    config = ChatConfig.from_env()
+
+    assert config.api_key is None
+    assert config.base_url is None
+    assert config.model == DEFAULT_MODEL
+
+
+def test_config_uses_default_model(monkeypatch):
+    monkeypatch.delenv("CODEX_CHAT_MODEL", raising=False)
+
+    config = ChatConfig.from_env(api_key="key")
+
+    assert config.model == DEFAULT_MODEL
+
+
+def test_config_uses_default_system_rules(monkeypatch):
+    monkeypatch.setenv("CODEX_CHAT_SYSTEM_RULES", "Answer in English.\nKeep answers short.")
+
+    config = ChatConfig.from_env(api_key="key")
+
+    assert config.system_rules == DEFAULT_SYSTEM_RULES
+
+
+def test_config_accepts_system_rules_as_function_parameter(monkeypatch):
+    monkeypatch.setenv("CODEX_CHAT_SYSTEM_RULES", "ignored")
+
+    config = ChatConfig.from_env(api_key="key", system_rules=("Answer in English.", "Keep answers short."))
+
+    assert config.system_rules == ("Answer in English.", "Keep answers short.")

codex_chat_bot-0.1.0/tests/test_session.py

@@ -0,0 +1,211 @@
+from types import SimpleNamespace
+import json
+
+import pytest
+
+from codex_chat_bot import ChatConfig, ChatSession, Message
+from codex_chat_bot.session import _extract_response_text
+
+
+class FakeResponses:
+    def __init__(self):
+        self.calls = []
+
+    def create(self, **kwargs):
+        self.calls.append(kwargs)
+        user_message = kwargs["input"][-1]["content"]
+        return SimpleNamespace(output_text=f"answer: {user_message}")
+
+
+class FakeClient:
+    def __init__(self):
+        self.responses = FakeResponses()
+
+
+def make_session(**config_overrides):
+    config = ChatConfig(api_key="test-key", base_url="https://api.example/v1", model="test-model", **config_overrides)
+    client = FakeClient()
+    return ChatSession(config=config, client=client), client
+
+
+def test_session_sends_full_single_session_history():
+    session, client = make_session(system_rules=("Follow the test.",))
+
+    assert session.ask("hello") == "answer: hello"
+    assert session.ask("what did I say?") == "answer: what did I say?"
+
+    second_input = client.responses.calls[1]["input"]
+    assert second_input == [
+        {"role": "system", "content": "Follow the test."},
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "answer: hello"},
+        {"role": "user", "content": "what did I say?"},
+    ]
+
+
+def test_session_adds_system_rules_to_system_message():
+    session, client = make_session(
+        system_rules=("Follow the test.", "Answer in English.", "Keep answers short."),
+    )
+
+    session.ask("hello")
+
+    assert client.responses.calls[0]["input"][0] == {
+        "role": "system",
+        "content": "Follow the test.\nAnswer in English.\nKeep answers short.",
+    }
+
+
+def test_reset_clears_conversation_but_keeps_system_rules():
+    session, _ = make_session(system_rules=("Stay brief.",))
+
+    session.ask("hello")
+    session.reset()
+
+    assert session.messages == (Message(role="system", content="Stay brief."),)
+
+
+def test_reset_can_override_system_rules():
+    session, _ = make_session(system_rules=("Stay brief.", "Use Markdown."))
+
+    session.reset(system_rules=("No Markdown.",))
+
+    assert session.messages == (
+        Message(role="system", content="No Markdown."),
+    )
+
+
+def test_history_limit_keeps_latest_non_system_messages():
+    session, _ = make_session(system_rules=("sys",), max_history_messages=2)
+
+    session.ask("one")
+    session.ask("two")
+
+    assert session.messages == (
+        Message(role="system", content="sys"),
+        Message(role="user", content="two"),
+        Message(role="assistant", content="answer: two"),
+    )
+
+
+def test_session_exports_and_imports_history_json():
+    session, _ = make_session(system_rules=("Follow the test.",))
+
+    session.ask("hello")
+    exported = session.export_history_json()
+
+    assert '\n    "messages": [' in exported
+
+    payload = json.loads(exported)
+    assert payload == {
+        "messages": [
+            {"role": "system", "content": "Follow the test."},
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "answer: hello"},
+        ]
+    }
+
+    restored, client = make_session(system_rules=("ignored",))
+    restored.load_history_json(exported)
+    restored.ask("continue")
+
+    assert client.responses.calls[0]["input"] == [
+        {"role": "system", "content": "Follow the test."},
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "answer: hello"},
+        {"role": "user", "content": "continue"},
+    ]
+
+
+def test_session_saves_and_loads_history_file(tmp_path):
+    history_file = tmp_path / "history.json"
+    session, _ = make_session(system_rules=("Follow the test.",))
+    session.ask("hello")
+
+    session.save_history(history_file)
+
+    restored, _ = make_session(system_rules=("ignored",))
+    restored.load_history(history_file)
+
+    assert restored.messages == session.messages
+
+
+def test_session_bind_history_loads_existing_file_and_saves_updates(tmp_path):
+    history_file = tmp_path / "history.json"
+    history_file.write_text(
+        """
+{
+    "messages": [
+        {
+            "role": "system",
+            "content": "Persisted system."
+        },
+        {
+            "role": "user",
+            "content": "old"
+        },
+        {
+            "role": "assistant",
+            "content": "answer: old"
+        }
+    ]
+}
+""".strip(),
+        encoding="utf-8",
+    )
+    session, client = make_session(system_rules=("ignored",))
+
+    session.bind_history(history_file)
+    session.ask("new")
+
+    assert client.responses.calls[0]["input"] == [
+        {"role": "system", "content": "Persisted system."},
+        {"role": "user", "content": "old"},
+        {"role": "assistant", "content": "answer: old"},
+        {"role": "user", "content": "new"},
+    ]
+    assert json.loads(history_file.read_text(encoding="utf-8")) == {
+        "messages": [
+            {"role": "system", "content": "Persisted system."},
+            {"role": "user", "content": "old"},
+            {"role": "assistant", "content": "answer: old"},
+            {"role": "user", "content": "new"},
+            {"role": "assistant", "content": "answer: new"},
+        ]
+    }
+
+
+def test_session_bind_history_creates_file_and_tracks_reset(tmp_path):
+    history_file = tmp_path / "history.json"
+    session, _ = make_session(system_rules=("Follow the test.",))
+
+    session.bind_history(history_file)
+    session.reset(system_rules=("After reset.",))
+
+    assert json.loads(history_file.read_text(encoding="utf-8")) == {
+        "messages": [{"role": "system", "content": "After reset."}]
+    }
+
+
+def test_session_rejects_invalid_history_json():
+    session, _ = make_session()
+
+    with pytest.raises(ValueError, match="invalid role"):
+        session.load_history_json('{"messages": [{"role": "tool", "content": "nope"}]}')
+
+
+def test_extract_response_text_from_output_parts():
+    response = {
+        "output": [
+            {"content": [{"type": "output_text", "text": "hello"}, {"type": "output_text", "text": " world"}]}
+        ]
+    }
+
+    assert _extract_response_text(response) == "hello world"
+
+
+def test_empty_message_is_rejected():
+    session, _ = make_session()
+
+    with pytest.raises(ValueError):
+        session.ask("   ")