Virtual Assistant Version 0.01

-

Build a Tiny Command-Line Virtual Assistant in Python (Step-by-Step)

Want a lightweight virtual assistant you can run in the terminal and extend with your own commands? In this post we’ll build a clean, single-file assistant called va.py.

We’ll start from a bare read a command, evaluate the comment, print the response and the loop.

then layer on a command system, persistence (notes & todos), helpful built-ins, and a tiny intent guesser.

You’ll end up with:

  • a va> prompt (the loop)

  • a decorator-based command registry (easy to add commands)

  • persistent notes & todos stored at ~/.va_state.json

  • help, history, clear, exit, and more

  • a simple keyword-based intent fallback

Requires: Python 3.9+ (tested on 3.10/3.11).
Run with: python va.py

1) Start

We begin with a loop that reads a line, splits it into a command and arguments, and exits cleanly on Ctrl+C / Ctrl+D.

#!/usr/bin/env python3
import shlex, sys

BANNER = """\
Command-line Virtual Assistant
Type 'help' to see commands. Ctrl+C or 'exit' to quit.
"""

def main():
    print(BANNER)
    while True:                # The loop
        try:
            line = input("va> ").strip()        # Get an input
        except (EOFError, KeyboardInterrupt):
            print()
            sys.exit(0)                         # exit the loop
        if not line:
            continue
        try:
            parts = shlex.split(line)           # Basic command parsing
        except ValueError as e:
            print(f"Parse error: {e}")
            continue
        cmd, *args = parts
        print(f"(debug) command={cmd} args={args}")    # temp print command

if __name__ == "__main__":
    main()

  • shlex.split handles quoted strings correctly.

  • We’ll replace the (debug) print with our real command handler next.

2) Add a Command Registry (with a Decorator)

We want commands like help, note, todo to be easy to add. A tiny registry + decorator does the trick.

COMMANDS = {}
ALIASES = {}

def command(name, *, aliases=(), help=""):
    def wrap(func):
        COMMANDS[name] = {"fn": func, "help": help.strip()}
        for a in aliases:
            ALIASES[a] = name
        return func
    return wrap

def resolve(cmd):
    if cmd in COMMANDS:
        return cmd
    if cmd in ALIASES:
        return ALIASES[cmd]
    return None

Update the main loop to use it:

cmd_token, *args = parts
cmd = resolve(cmd_token)
if not cmd:
    print(f"Unknown command: {cmd_token}. Try 'help'.")
    continue
COMMANDS[cmd]["fn"](args)

Now we can define commands like:

@command("say", help="say <text> — repeat your text")
def _say(args):
    if not args:
        print("Usage: say <text>")
        return
    print(" ".join(args))

3) Pretty Output & Time Helpers

A couple of niceties you’ll use everywhere.

import datetime as dt, textwrap

def now():
    return dt.datetime.now()

def echo_box(s: str):
    w = 72
    lines = textwrap.wrap(s, width=w) if "\n" not in s else s.splitlines()
    print("┌" + "─"*w + "┐")
    for line in lines:
        print("│" + line.ljust(w) + "│")
    print("└" + "─"*w + "┘")

Add a time command:

@command("time", aliases=("date",), help="time — show current date/time")
def _time(args):
    print(now().strftime("%Y-%m-%d %H:%M:%S"))

4) Persistence: Save Notes & Todos to Disk

We’ll keep state as JSON in the current working directory as the file .va_state.json.

import json, os
from pathlib import Path

from pathlib import Path
STATE_PATH = Path.cwd() / ".va_state.json"

def load_state():
    if STATE_PATH.exists():
        try:
            return json.loads(STATE_PATH.read_text())
        except Exception:
            pass
    return {"notes": [], "todos": [], "created": now().isoformat()}

def save_state(state):
    STATE_PATH.write_text(json.dumps(state, indent=2))

STATE = load_state()

5) Implement note and todo

Notes

This creates a note and saves it to a file located in the virtual assistants current working directory. This can also list notes that have been saved.
@command("note", aliases=("addnote","n"), help="""
note <text> — save a quick note
note list     — list notes
""")
def _note(args):
    if not args:
        print("Usage: note <text> | note list")
        return
    if args[0] == "list":
        if not STATE["notes"]:
            print("(no notes)")
        else:
            for i, n in enumerate(STATE["notes"], 1):
                print(f"{i}. {n['when']} — {n['text']}")
        return
    text = " ".join(args)
    STATE["notes"].append({"when": now().isoformat(timespec="seconds"), "text": text})
    save_state(STATE)
    print("Saved note.")

Todos

This creates a todo list and saves it to a file located in the virtual assistants current working directory. This can also list items that are on the todo list.
@command("todo", aliases=("t","task"), help="""
todo add <text>     — add a todo
todo list           — list todos
todo done <number>  — mark done (by number)
""")
def _todo(args):
    if not args or args[0] not in ("add","list","done"):
        print("Usage:\n  todo add <text>\n  todo list\n  todo done <number>")
        return
    sub = args[0]
    if sub == "add":
        text = " ".join(args[1:]).strip()
        if not text:
            print("Provide a task description.")
            return
        STATE["todos"].append({"text": text, "done": False,
                               "created": now().isoformat(timespec="seconds")})
        save_state(STATE)
        print("Added.")
    elif sub == "list":
        if not STATE["todos"]:
            print("(no todos)")
            return
        for i, t in enumerate(STATE["todos"], 1):
            box = "[x]" if t["done"] else "[ ]"
            print(f"{i:2}. {box} {t['text']}")
    elif sub == "done":
        if len(args) < 2 or not args[1].isdigit():
            print("Provide the todo number to mark done.")
            return
        idx = int(args[1]) - 1
        if idx < 0 or idx >= len(STATE["todos"]):
            print("Invalid number.")
            return
        STATE["todos"][idx]["done"] = True
        save_state(STATE)
        print("Marked done.")

6) Help, History, Clear, Exit

A few essentials for a pleasant CLI, we can add history of commands made, a clear the screen function, exit command and also a help feature to list all the commands that can be made.

HISTORY = []

@command("help", aliases=("?",), help="""
help [command] — show help (for all commands or a specific one)
""")
def _help(args):
    if args:
        cmd = resolve(args[0])
        if not cmd:
            print(f"No such command: {args[0]}")
            return
        h = COMMANDS[cmd]["help"] or "(no help text)"
        echo_box(f"{cmd}\n\n{h}")
        return
    echo_box("Commands:")
    names = sorted(COMMANDS)
    width = max(len(n) for n in names)
    for n in names:
        h = COMMANDS[n]["help"].splitlines()[0] if COMMANDS[n]["help"] else ""
        print(f"  {n.ljust(width)}  {h}")

@command("history", help="history — show recent commands")
def _history(args):
    for i, line in enumerate(HISTORY[-50:], 1):
        print(f"{i:2}: {line}")

@command("clear", help="clear — clear the screen")
def _clear(args):
    os.system("cls" if os.name == "nt" else "clear")

@command("exit", aliases=("quit","q"), help="exit — leave the assistant")
def _exit(args):
    print("Bye!")
    sys.exit(0)

And record input lines in the main loop:

HISTORY.append(line)

7) A Tiny Intent Fallback (Keyword Guess)

If the user types something like “remember to buy milk”, we can guess they meant note.

INTENT_MAP = [
    ({"note","remember","jot"}, "note"),
    ({"task","todo","remind"}, "todo"),
    ({"time","date","clock"}, "time"),
    ({"repeat","say","echo"}, "say"),
    ({"help"}, "help"),
]

def guess_intent(tokens):
    words = set(w.lower() for w in tokens)
    for keys, cmd in INTENT_MAP:
        if keys & words:
            return cmd
    return None

Wire it into the main loop where we previously handled unknown commands:

cmd = resolve(cmd_token)
if not cmd:
    guess = guess_intent(parts)
    if guess:
        cmd = guess
        # pass through args, lightly cleaned
        args = [a for a in args if a.lower() not in ("please","me","a","the")]
        if cmd == "note" and not args:
            args = [" ".join(parts)]  # treat whole line as the note
    else:
        print(f"Unknown command: {cmd_token}. Try 'help'.")
        continue

8) Final va.py (Full Listing)

Try putting this all together yourself or check it out on my GitHub

9) Try It Out

python va.py
va> note Buy 74LS258 chips
va> note list
va> todo add Finish 6502 Part 3 post
va> todo list
va> time
va> help todo
va> exit

10) Where to Go Next

  • New commands: add with @command("name", aliases=(...), help="...").

  • Timers/alarms: schedule in-process timers (warn: they end when you exit).

  • Plugin loader: import commands from a plugins/ folder.

  • Search: add a search command to find text across notes/todos.

  • Better NLP: replace the keyword intent with a small rules engine.

This is a basic example of what can be done and I hope to expand upon it in future and add more functionality and document this process along the way. 

Comments

Post a Comment

Popular posts from this blog

Math Behind Logic Gates

-
Image
Understanding the Real Electronics Behind Logic Gates (The Practical Math Behind Digital Circuits) When we build circuits with logic chips like the 74LS series, it’s easy to think only in 1s and 0s. But under the hood, every logic gate follows the same rules as any other circuit, Ohm’s Law, current limits, and voltage thresholds. So yes, there is real-world math behind those blinking LEDs and logic tables.  1. Logic Levels — The Digital View At the logic level, everything is simple: 0 V → LOW (logic 0) 5 V → HIGH (logic 1) We don’t care about exact voltages here just whether a signal crosses a defined threshold. For TTL (Transistor-Transistor Logic) chips like the 74LS86 XOR gate , these thresholds are: This means a logic gate “decides” based on whether the voltage is above or below that boundary, which is how binary logic becomes real voltage levels. 2. Inside the Circuit — Real Electrical Math Even though logic circuits process bits, they still obey Ohm’s Law ...
Read more

6502 - Part 2 Reset and Clock Circuit

-
Image
6502 Retro Console Part 2 Add a Reset and Clock Circuit In Part 1 we powered up the 6502 and watched it running a NOP test with just the CPU and LEDs on the address bus. Now we’ll give it a clock and a clean start every time you power on, rather than relying on a function generator. In this post we will cover a simple 555 Timer Clock circuit and reset circuit. 555 Timer The 6502 needs a steady pulse on its Φ0 (pin 37) to step through instructions. A NE555 timer is perfect for low-speed testing reliable, simple, and easy to wire. Parts List NE555 timer 1 kΩ resistor 10 kΩ resistor 100 nF capacitor (timing) 0.1 µF capacitor (decoupling) Breadboard + jumper wires Circuit Diagram How to Wire It Add a 0.1 µF decoupling cap across the +5V and GND rails stability. Typical speed: ≈ 7–10 kHz perfect for a visible NOP test. Use larger resistors or capacitors to slow it down. Tip: Swap the timing capacitor for 1 µF and the 10 kΩ for 100 kΩ to step slowly enough ...
Read more

Building a 6502 NOP Test

-
Image
 The Simplest Working 8-bit CPU Circuit Before we start building a full retro console, let’s do something beautifully simple get a 6502 CPU to run,  no RAM, no ROM, no glue logic, just the chip, a few LEDs, and a clock. This is called a NOP test (No Operation). It’s the digital equivalent of “does it breathe?” What You’ll Need Part Purpose MOS 6502 CPU The heart of our system Bench power supply (5 V) Power for the CPU Function generator Clock source 8 × LEDs To watch address lines change 8 × 470 Ω resistors Current-limiters for the LEDs 1 × 0.1 µF capacitor Decoupling between VCC and GND Breadboard and jumper wires For connections MOS 6502 Cpu Pin Out Check your IC and its datasheet to ensure that you have the correct pin out map as the steps below may vary slightly. Step 1 — Power and Decoupling Give the 6502 a clean 5 V supply: VCC (pin 8) → +5 V VSS (pins 1 and 21) → Ground Place the 0.1 µF capacitor between VCC and VSS close to the chip. That tiny capacitor...
Read more