AetherChat CLI Assistant

What this repository is

This repository contains a Python CLI chatbot that uses OpenAI models and a weather tool integration.

The project is structured with clear layers:

• src/app: startup and configuration loading.
• src/api: CLI interaction loop.
• src/core: chatbot orchestration and tool definitions.
• src/infra: external clients (OpenAI and Open-Meteo).
• src/services: application services used by the API layer.

The application entry point is python -m src.app.main.

What it is for

The assistant is designed to:

• hold conversational interactions through the terminal,
• answer in Spanish with a poetic style,
• call a weather tool when weather-related requests appear,
• switch between OpenAI Responses API and Chat Completions API with an environment flag.

In short, this is a practical baseline for a tool-enabled conversational agent with clean separation between domain, services, and infrastructure.

Environment

Runtime requirements

• Python 3.12+ (Docker image uses python:3.12-slim)
• Internet access (OpenAI + Open-Meteo APIs)
• OpenAI API key

Python dependencies

Dependencies are pinned in requirements.txt.

Install locally:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment variables

Use .env.example as a template.

Required:

• OPENAI_API_KEY

Optional (with defaults):

• OPENAI_MODEL (default: gpt-5.4-mini)
• OPENAI_MAX_OUTPUT_TOKENS (default: 500)
• OPENAI_TEMPERATURE (default: 0.7)
• OPENAI_MODE (responses or chat_completions, default: responses)
• LOG_LEVEL (default: INFO)

Create your local environment file:

cp .env.example .env
# then edit .env and set OPENAI_API_KEY

How to use it

Run locally

python -m src.app.main

You will get an interactive prompt:

• type a message and press Enter,
• type exit, quit, or salir to stop.

Run with Docker Compose

Build and run:

make build
make up

Or run one-off container sessions:

make run

Useful commands:

• make down: stop and remove containers
• make logs: follow app logs
• make shell: open shell in the app container

Switching OpenAI backend mode

Set OPENAI_MODE in .env:

• responses: uses the Responses API client.
• chat_completions: uses the Chat Completions API client.

No code change is needed; restart the app after updating the variable.