X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/6572373d4945cc5c504fc5f760d7de51fb245d3f..de170709599e849c6b409d247b800dc68b0c7ab7:/README.rst?ds=sidebyside diff --git a/README.rst b/README.rst index df03c4f..c9aaaee 100644 --- a/README.rst +++ b/README.rst @@ -2,8 +2,171 @@ OneChat ######### -OneChat is a Go program. It prints its name. It is in early development. -Linux is supported. +OneChat is one AI agent in a single chat that never ends. A daemon owns +the agent and its files, and a terminal client and a Telegram bot talk +to it. It is in early development. Linux is supported. + +**************** + Data directory +**************** + +OneChat keeps its data and its token file in one directory. It uses the +first of these: + +#. ``ONECHAT_DIR``, when it is set. +#. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute + path. A relative value is ignored. +#. ``~/.local/share/onechat``. With no home directory, OneChat exits + with an error. + +OneChat creates the directory with mode 0700. + +*************** + Configuration +*************** + +``config.json`` in the data directory holds the settings. OneChat does +not create it. A missing file or field takes the default, and an unknown +field is an error. + +.. code:: json + + { + "endpoint": "chatgpt", + "compactor": {"model": "gpt-6.1-sol", "effort": "high"} + } + +``endpoint`` + ``chatgpt`` (the default) sends model calls to the ChatGPT backend + with the subscription login. ``api`` sends them to the OpenAI API + with the key in ``OPENAI_API_KEY``, which must then be set. With + ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``. + +``compactor`` + The model and the reasoning effort of the summaries. The defaults are + ``gpt-6.1-sol`` and ``high``. + +******* + Login +******* + +The ``chatgpt`` endpoint needs a login with a ChatGPT account: + +.. code:: console + + onechat login + +The command shows a link and a code. Open the link on any device, enter +the code, and approve the login. Device code login must be allowed in +the ChatGPT security settings. OneChat writes the tokens to +``auth.json`` in the data directory, with mode 0600, and refreshes them +before they expire. The file belongs to OneChat only. Do not share it +with the Codex CLI, because each program rotates the refresh token and +logs the other out. + +******* + Agent +******* + +Start the daemon, and then the client in another terminal: + +.. code:: console + + onechat daemon + onechat chat + +The daemon owns the root agent in ``agent/`` in the data directory and +listens on the Unix socket ``onechat.sock`` there. In the client, each +line is a message to the agent, the line ``/stop`` interrupts the +running turn, and Ctrl-D ends the client. The client shows the replies, +the tool calls, and the first lines of each tool result as they happen. +It also shows each message that the user sends from another client, with +the client as a mark, such as ``[telegram] text``. The daemon is the +only process that uses the token file while it runs, so ``onechat +login`` and ``onechat probe`` refuse to start until it stops. + +The agent runs commands with bash as the user in its working directory, +with no sandbox. It has the rights of the user, also on the token file. + +``agent/config.json`` holds the settings of the agent. The first start +writes it with the defaults and a random ID. Do not change the ID: the +prompt cache key comes from it. + +.. code:: json + + { + "name": "OneChat", + "id": "0123456789abcdef0123456789abcdef", + "model": "gpt-6.1-sol", + "effort": "medium", + "workdir": "/home/user" + } + +``workdir`` is an absolute path, and its default is the home directory. +``agent/instructions.md`` holds the user's instructions: who they are, +how their files are organized, and how they want work done. The prompt +ends with them, and a change applies at the next call. + +********** + Telegram +********** + +The daemon also connects the agent to a Telegram bot when +``telegram.json`` exists in the data directory. It polls the Bot API for +new messages, so it needs no open port. + +#. Make a bot with BotFather and keep its token. + +#. Find your numeric Telegram user ID. + +#. Write the token and the ID to ``telegram.json``, and give the file + mode 0600, because the token is a secret. The daemon refuses the file + with any other mode. + +#. Start the daemon, open a private chat with the bot, and write. + +.. code:: json + + {"token": "123456:ABC-token-from-BotFather", "owner": 123456789} + +The bot reads only the private chat of the owner and ignores all other +updates. Each text message goes to the agent as a user message, and the +line ``/stop`` interrupts the running turn. The bot sends the replies in +parts of at most 4096 characters, with their Markdown as Telegram +formats: bold, italic, strikethrough, code, code blocks, links, and +headings as bold text. When Telegram refuses the formats of a part, the +bot sends the part again as plain text. Each error goes as a short +message in plain text. It shows the typing action while a turn runs. It +does not send the tool calls. It sends each message that the user types +in the terminal client, with the mark ``[terminal]``. + +``agent/telegram-offset.json`` holds the ID of the next update. The bot +moves it past an update only after the message is durable in the log, so +a restart of the daemon does not lose a message. A crash just after the +write of a message can make the message repeat once. A network failure +or a rate limit makes the bot wait and try again, and does not stop the +daemon. + +******* + Probe +******* + +``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It +appends the first COUNT messages of LOG, one JSON object ``{"kind", +"text"}`` on each line, to a new chat in ``probe/`` in the data +directory, and builds its tree with real model calls. The calls use the +quota of the account. The run stops at the first failed call, after 660 +calls, or when the used percent of a quota window grows by more than 15 +points. At the end it reports the calls per message, the cached share of +the input tokens, the retries, the line sizes, and the quota at the +first and the last call. BUILDS, from 1 to 8, limits the model calls at +once in the run. + +A test writes a generated log of readable made-up messages: + +.. code:: console + + ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix ************* Development