LLMs and Generative AI › LLM APIs › Day 259

Hands-on lab — Day 259: Building a CLI Assistant

Commands

Setup

pip install -r requirements/requirements.txt

Run

python3 examples/building_a_cli_assistant_lib.py

Test

./tests/run_tests.sh

File tree

conftest.py
examples/building_a_cli_assistant_lib.py
examples/test_building_a_cli_assistant_lib.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/starter-run.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/building_a_cli_assistant_lib.py
starter/test_building_a_cli_assistant_lib.py
tests/run_tests.sh
tests/test_building_a_cli_assistant_lib.py
troubleshooting.md

Lab README

Lab: Day 259 -- Building a CLI Assistant

Lesson

Day number: 259 of 365. Course: Course06-SS02 (LLMs and Generative AI - LLM APIs). Topic: Building a Command-Line AI Assistant Core in Python.

Purpose

Build and test a Modular CLI Assistant Core in Python. Implement sliding window memory management, slash command routing, tool registration, and session token/financial tracking.

Learning objectives

  • Build context message arrays with pinned system prompts and sliding history.
  • Implement slash command handlers for session management.
  • Register and execute local tools.
  • Track cumulative session token and cost expenditure.

Prerequisites

  • Day 258 (Cost, Caching, and Rate Limits).
  • Python 3.11+ with Pytest.

Supported operating systems

  • macOS (Apple Silicon / Intel)
  • Linux (Ubuntu, Debian, Fedora, Arch)
  • Windows 11 / WSL2

Hardware requirements

  • 1+ CPU cores.
  • 1 GB RAM.
  • 100 MB disk space.

Required software

  • Python 3.11 or newer.
  • pip package manager.
  • virtualenv or venv module.

Free and open-source options

Python and standard collections/typing modules are open source.

Installation

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

File structure

  • starter/building_a_cli_assistant_lib.py: Student scaffold file.
  • examples/building_a_cli_assistant_lib.py: Complete reference implementation.
  • tests/test_building_a_cli_assistant_lib.py: Pytest automated validation suite.
  • expected-output/: Verified output logs and baseline values.

How to run

Execute the reference demonstration script:

python3 examples/building_a_cli_assistant_lib.py

What the commands do

  • Builds message context array.
  • Processes /cost slash command.
  • Runs unit test assertions.

Expected output

Assistant Demo Executed. Context Len: 3, Cost Msg: Session Tokens: 100 | Total Cost: $0.0003

Validation steps

  1. Verify system prompt remains pinned at message index 0.
  2. Confirm sliding window evicts oldest non-system turns when max turns exceeded.
  3. Validate /clear empties conversational history.
  4. Ensure all unit test assertions pass.

Tests

Run the test runner script:

./tests/run_tests.sh

Cleanup

find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name ".pytest_cache" -exec rm -rf {} +

Troubleshooting

  • Memory window sizing error: Ensure deque maxlen is initialized to max_history_turns * 2.

Security notes

All assistant state runs locally in memory.

Extension exercises

  1. Implement a Git commit message generator slash command (/commit).
  2. Build an automated conversation session exporter (/export).
  • Lesson title: Building a CLI Assistant
  • Day number: 259 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-259-building-a-cli-assistant
  • Lab files: everything you need is in this directory — follow “How to run” below.
  • Browse the course locally: from the repository root, this lab also appears in the course website at /labs/day-259-building-a-cli-assistant when the site is running.

Expected output

FIELDS.md

# Expected Output Fields: Day 259

- `Assistant Demo`: Status of CLI assistant core execution.

examples-run.txt

Assistant Demo Executed. Context Len: 3, Cost Msg: Session Tokens: 100 | Total Cost: $0.0003

measured-values.txt

Assistant Demo: Success
Context Length: 3
Recorded Cost: $0.0003

starter-run.txt

Starter scaffold executed. Ready for student implementation.

test-run.txt

============================= test session starts ==============================
collected 4 items

tests/test_building_a_cli_assistant_lib.py::test_context_builder_and_system_pinning PASSED [ 25%]
tests/test_building_a_cli_assistant_lib.py::test_sliding_window_eviction PASSED             [ 50%]
tests/test_building_a_cli_assistant_lib.py::test_slash_commands PASSED                     [ 75%]
tests/test_building_a_cli_assistant_lib.py::test_tool_registration PASSED                 [100%]

============================== 4 passed in 0.38s ===============================

Source files

conftest.py (585 bytes)
"""Make this lab importable when the suite runs.

pytest puts the test file's own directory on sys.path, not the lab root, so a
test that does `from examples.<module> import ...` -- or imports a module that
lives in examples/ directly -- fails without this. Putting it here rather than
in run_tests.sh means a bare `pytest` from the lab root works too.
"""

import os
import sys

LAB = os.path.dirname(os.path.abspath(__file__))
for candidate in (LAB, os.path.join(LAB, "examples")):
    if os.path.isdir(candidate) and candidate not in sys.path:
        sys.path.insert(0, candidate)
examples/building_a_cli_assistant_lib.py (2310 bytes)
import time
from typing import Dict, Any, List, Optional
from collections import deque

class CLIAssistantCore:
    def __init__(self, system_prompt: str, max_history_turns: int = 6):
        self.system_prompt = system_prompt
        self.max_history_turns = max_history_turns
        self.history: deque = deque(maxlen=max_history_turns * 2)
        self.tools: Dict[str, Any] = {}
        self.session_cost_usd = 0.0
        self.total_tokens_consumed = 0

    def register_tool(self, name: str, func: Any):
        self.tools[name] = func

    def build_message_context(self, new_user_message: str) -> List[Dict[str, Any]]:
        messages = [{"role": "system", "content": self.system_prompt}]
        for turn in self.history:
            messages.append(turn)
        messages.append({"role": "user", "content": new_user_message})
        return messages

    def record_turn(self, user_text: str, assistant_text: str, tokens: int = 150, cost: float = 0.0005):
        self.history.append({"role": "user", "content": user_text})
        self.history.append({"role": "assistant", "content": assistant_text})
        self.total_tokens_consumed += tokens
        self.session_cost_usd += cost

    def handle_slash_command(self, cmd: str) -> str:
        cmd = cmd.strip().lower()
        if cmd == "/help":
            return "Available commands: /help, /cost, /clear, /tools, /exit"
        elif cmd == "/cost":
            return f"Session Tokens: {self.total_tokens_consumed} | Total Cost: ${self.session_cost_usd:.4f}"
        elif cmd == "/clear":
            self.history.clear()
            return "Conversation history cleared. System prompt preserved."
        elif cmd == "/tools":
            return f"Registered Tools: {list(self.tools.keys())}"
        return f"Unknown command: {cmd}"

def run_assistant_demo():
    assistant = CLIAssistantCore("You are a helpful assistant.", max_history_turns=2)
    assistant.register_tool("calc", lambda x, y: x + y)
    assistant.record_turn("Hello", "Hi there!", 100, 0.0003)
    ctx = assistant.build_message_context("How are you?")
    cost_msg = assistant.handle_slash_command("/cost")
    print(f"Assistant Demo Executed. Context Len: {len(ctx)}, Cost Msg: {cost_msg}")
    return ctx, cost_msg

if __name__ == "__main__":
    run_assistant_demo()
examples/test_building_a_cli_assistant_lib.py (1695 bytes)
import pytest
from examples.building_a_cli_assistant_lib import (
    CLIAssistantCore
)

def test_context_builder_and_system_pinning():
    assistant = CLIAssistantCore("System instructions here.", max_history_turns=2)
    ctx = assistant.build_message_context("First question")

    assert len(ctx) == 2
    assert ctx[0]["role"] == "system"
    assert ctx[0]["content"] == "System instructions here."
    assert ctx[1]["role"] == "user"
    assert ctx[1]["content"] == "First question"

def test_sliding_window_eviction():
    assistant = CLIAssistantCore("Sys", max_history_turns=2) # Max 4 items in deque (2 pairs)
    assistant.record_turn("Q1", "A1")
    assistant.record_turn("Q2", "A2")
    assistant.record_turn("Q3", "A3") # Q1, A1 should be evicted

    ctx = assistant.build_message_context("Q4")
    # Expected: sys + Q2 + A2 + Q3 + A3 + Q4 = 6 items
    assert len(ctx) == 6
    assert ctx[1]["content"] == "Q2"
    assert ctx[3]["content"] == "Q3"
    assert ctx[5]["content"] == "Q4"

def test_slash_commands():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("test_tool", lambda: "ok")
    assistant.record_turn("Q", "A", tokens=500, cost=0.002)

    assert "Available commands" in assistant.handle_slash_command("/help")
    assert "$0.0020" in assistant.handle_slash_command("/cost")
    assert "test_tool" in assistant.handle_slash_command("/tools")

    clear_res = assistant.handle_slash_command("/clear")
    assert "cleared" in clear_res
    assert len(assistant.history) == 0

def test_tool_registration():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("add", lambda a, b: a + b)
    assert assistant.tools["add"](10, 5) == 15
metadata.yml (437 bytes)
lesson_id: D259
day: 259
kind: lab
languages:
  - python
setup_commands:
  - 'pip install -r requirements/requirements.txt'
run_commands:
  - 'python3 examples/building_a_cli_assistant_lib.py'
test_commands:
  - './tests/run_tests.sh'
cleanup_commands:
  - 'find . -type d -name "__pycache__" -exec rm -rf {} +'
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: 'macos-arm64'
requirements/requirements.txt (41 bytes)
torch>=2.2.0
numpy>=1.26.0
pytest>=8.0.0
starter/building_a_cli_assistant_lib.py (829 bytes)
import time
from typing import Dict, Any, List, Optional
from collections import deque

class CLIAssistantCore:
    def __init__(self, system_prompt: str, max_history_turns: int = 6):
        # TODO: Initialize attributes and sliding history deque
        pass

    def register_tool(self, name: str, func: Any):
        # TODO: Register tool
        pass

    def build_message_context(self, new_user_message: str) -> List[Dict[str, Any]]:
        # TODO: Construct message context with system prompt and history
        pass

    def record_turn(self, user_text: str, assistant_text: str, tokens: int = 150, cost: float = 0.0005):
        # TODO: Record turn and update ledger
        pass

    def handle_slash_command(self, cmd: str) -> str:
        # TODO: Process slash commands (/help, /cost, /clear, /tools)
        pass
starter/test_building_a_cli_assistant_lib.py (1695 bytes)
import pytest
from examples.building_a_cli_assistant_lib import (
    CLIAssistantCore
)

def test_context_builder_and_system_pinning():
    assistant = CLIAssistantCore("System instructions here.", max_history_turns=2)
    ctx = assistant.build_message_context("First question")

    assert len(ctx) == 2
    assert ctx[0]["role"] == "system"
    assert ctx[0]["content"] == "System instructions here."
    assert ctx[1]["role"] == "user"
    assert ctx[1]["content"] == "First question"

def test_sliding_window_eviction():
    assistant = CLIAssistantCore("Sys", max_history_turns=2) # Max 4 items in deque (2 pairs)
    assistant.record_turn("Q1", "A1")
    assistant.record_turn("Q2", "A2")
    assistant.record_turn("Q3", "A3") # Q1, A1 should be evicted

    ctx = assistant.build_message_context("Q4")
    # Expected: sys + Q2 + A2 + Q3 + A3 + Q4 = 6 items
    assert len(ctx) == 6
    assert ctx[1]["content"] == "Q2"
    assert ctx[3]["content"] == "Q3"
    assert ctx[5]["content"] == "Q4"

def test_slash_commands():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("test_tool", lambda: "ok")
    assistant.record_turn("Q", "A", tokens=500, cost=0.002)

    assert "Available commands" in assistant.handle_slash_command("/help")
    assert "$0.0020" in assistant.handle_slash_command("/cost")
    assert "test_tool" in assistant.handle_slash_command("/tools")

    clear_res = assistant.handle_slash_command("/clear")
    assert "cleared" in clear_res
    assert len(assistant.history) == 0

def test_tool_registration():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("add", lambda a, b: a + b)
    assert assistant.tools["add"](10, 5) == 15
tests/run_tests.sh (227 bytes)
#!/usr/bin/env bash
set -euo pipefail
echo "========================================"
echo "Running Day 259 Lab Test Suite"
echo "========================================"
pytest tests/ -v
echo "All tests passed successfully."
tests/test_building_a_cli_assistant_lib.py (1695 bytes)
import pytest
from examples.building_a_cli_assistant_lib import (
    CLIAssistantCore
)

def test_context_builder_and_system_pinning():
    assistant = CLIAssistantCore("System instructions here.", max_history_turns=2)
    ctx = assistant.build_message_context("First question")

    assert len(ctx) == 2
    assert ctx[0]["role"] == "system"
    assert ctx[0]["content"] == "System instructions here."
    assert ctx[1]["role"] == "user"
    assert ctx[1]["content"] == "First question"

def test_sliding_window_eviction():
    assistant = CLIAssistantCore("Sys", max_history_turns=2) # Max 4 items in deque (2 pairs)
    assistant.record_turn("Q1", "A1")
    assistant.record_turn("Q2", "A2")
    assistant.record_turn("Q3", "A3") # Q1, A1 should be evicted

    ctx = assistant.build_message_context("Q4")
    # Expected: sys + Q2 + A2 + Q3 + A3 + Q4 = 6 items
    assert len(ctx) == 6
    assert ctx[1]["content"] == "Q2"
    assert ctx[3]["content"] == "Q3"
    assert ctx[5]["content"] == "Q4"

def test_slash_commands():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("test_tool", lambda: "ok")
    assistant.record_turn("Q", "A", tokens=500, cost=0.002)

    assert "Available commands" in assistant.handle_slash_command("/help")
    assert "$0.0020" in assistant.handle_slash_command("/cost")
    assert "test_tool" in assistant.handle_slash_command("/tools")

    clear_res = assistant.handle_slash_command("/clear")
    assert "cleared" in clear_res
    assert len(assistant.history) == 0

def test_tool_registration():
    assistant = CLIAssistantCore("Sys")
    assistant.register_tool("add", lambda a, b: a + b)
    assert assistant.tools["add"](10, 5) == 15

Troubleshooting

Troubleshooting: Day 259 - Building a CLI Assistant

Common Issues

  1. System prompt missing after turn eviction:
    • Cause: Putting system prompt inside the sliding deque.
    • Fix: Prepend the immutable system prompt explicitly in build_message_context.

Security notes

Security & Privacy: Day 259 - Building a CLI Assistant

Security Guidance

  • Sandbox tool file operations to the current workspace directory to prevent path traversal vulnerabilities.