Linux_post_install/DOC/howto/ai.md

How-To: pos ai

Chat with Google Gemini — from the terminal and through the Telegram bot. Tools: gemini (ask, chat, models).

Tool	What it does
pos ai gemini ask "<prompt>"	One-shot answer to stdout (scriptable)
pos ai gemini ask --session <name> "…"	Same, but remembers prior turns
pos ai gemini chat	Interactive multi-turn conversation
pos ai gemini models	List available model ids
pos ai gemini sessions	List/clear persistent sessions (reset <name>)

Shared flags: --model <id> overrides the model; --system "<text>" adds a system instruction to every turn (kept out of the session file).

---

First run — get a key, configure, chat

1. Get a free API key from https://aistudio.google.com/apikey (requires a Google account).

2. Configure it (masked input):

   pos config ai          # enter AI_GEMINI_API_KEY
   

3. Test:

   pos ai gemini ask "Explain DNS in one line"
   pos ai gemini models                 # verify the default model id is live
   pos ai gemini chat                   # multi-turn conversation
   

ai.env lives at ~/.config/linux_post_install/ai.env (chmod 600); pos config ai is the only place the key is written. The key is never printed by pos.

From the Telegram bot

Once pos ai gemini ask works, any non-command message starting with ai is answered by the model — no bot map entry needed:

you:    ai what is Nvidia
bot:    NVIDIA is a company best known for GPUs...

The bridge lives in the Telegram listener's handle_message (it calls pos ai gemini ask); only the owner chat is served, so your key stays private. Set a different model per message:

you:    ai --model gemini-2.5-flash explain a Raft consensus log

Telegram memory & formatting

Each chat has its own persistent session (telegram-<chat id>), so the model remembers the conversation; ai /reset clears it. The listener passes a system prompt telling the model it is answering in a Telegram chat — so it uses emojis and stays lively — and strips markdown (**x**, backticks, #, links…) from the reply before sending it, since messages go out as plain text.

Recipes

• Answer from a file: pos ai gemini ask "$(cat notes.txt)"
• Pipe into it: echo "fix this: $(cat error.log)" | pos ai gemini ask
• Answer in a cron job: pos ai gemini ask "summarize today's git log" > /tmp/ai_digest.txt
• Change the default model:

  pos config ai          # set AI_GEMINI_MODEL, or:
  AI_GEMINI_MODEL=gemini-2.5-flash pos ai gemini ask "hi"
  

How it works

• ask POSTs contents:[{role:user, parts:[{text:"…"}]}] to https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent with the key in the x-goog-api-key header, and prints .candidates[0].content.parts[].text — nothing else.
• chat keeps the whole conversation in memory as a growing contents[] array, so later turns have earlier context. /reset drops it.
• On a non-2xx response the API's error.message is shown and the exit code is non-zero — so scripts can rely on ask failing loudly.

Troubleshooting

• ask errors "No Gemini API key — run 'pos config ai'" → the key isn't set (or ai.env isn't readable). Run pos config ai.
• API error 400 → the model id is wrong or the prompt is too long for the model's context window; check pos ai gemini models.
• API error 429 → rate limit (free tier); wait and retry, or use a different model.
• Nothing in Telegram for ai … → the listener daemon must be running (pos communication telegram listener --status); the bot token and owner chat id must match pos config telegram.

---

Related

• Reference: DOC/POS.md → ai
• Telegram bridge context: communication.md