codex-chat-bot 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+codex_chat_bot/__init__.py,sha256=WvIBwz0w0e3d7TYJzxF6RqFrVwaghlHGzj7JP1ZzIv8,487
+codex_chat_bot/cli.py,sha256=XUOK_tgcaQfaTgTrMtKk8R3KMO49qi09kzs0iLpgJEo,7546
+codex_chat_bot/config.py,sha256=D-IewKcpzG8l5fxRdI1-FiuB-_M_MOhAPy61q7ZGFQY,2548
+codex_chat_bot/errors.py,sha256=G0PsXacnxetZM_3B8N0Xa-FSRIg1ipgxNvCwG8E0mz0,379
+codex_chat_bot/session.py,sha256=4rMH40f5O5bmXX5ZZebLqkqz4GhUMmqMXHUycEmjQHs,7808
+codex_chat_bot-0.1.0.dist-info/METADATA,sha256=0CPgFvNOzYo3NgTLAKoI62umnQNQGqPM6qMTY6hL-rE,3494
+codex_chat_bot-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codex_chat_bot-0.1.0.dist-info/entry_points.txt,sha256=dsb0UKu37uXDthxyU8SLnXqY-6y3a50QzLQRwCkz8SU,55
+codex_chat_bot-0.1.0.dist-info/RECORD,,

codex_chat_bot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_chat_bot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-chat = codex_chat_bot.cli:main