CataLogger: AI-Powered Cat Metric Logger

Table of Contents

• Overview
• How it Works
• Features
• Setup
  • Windows
  • Mac/Linux
  • AI Overview Setup
  • Self Packaging
• Usage

Overview

Keeping track of your cat's health can be difficult, especially when changes happen gradually over time. CataLogger is a CLI tool that lets you log daily metrics like weight, activity, appetite, water intake, and litter habits for each of your cats. When you want to check in on how they're doing, the built-in AI analyzes the logged data and provides a clear health overview, highlighting trends and flagging anything that might need a vet visit.

(Built for the HacktheKitty hackathon)

How it Works

The CLI is built with Python and SQLite3. It uses the third-party library Click to allow the user to interact with the script via a command line along with supporting user inputs as arguments. The user runs the main .exe by using it in the Windows Terminal or using the main.py script in other supported operating systems. There are 3 Python scripts found in the source code;

• main.py: The link between the user (front-end) and the other scripts (back-end).
• sql.py: Handles all connections with the database. (stored locally as cat-a-log.db)
• analyze.py: Contains all the AI connections. (uses groq as the main endpoint, llama-3.3-70b-versatile as the AI model)

When the user uses the app for the first time, they would probably think to add their cat as an entry to the database first before logging. When they use the add-entry command, this is what happens on the backend;

1. The arguments the user passed in (name, birth date, breed) will be received by main.py.
2. It then passes the arguments to sql.py, and runs the addEntry function.
3. The function executes a SQL command INSERT with cursor.execute. Using the '?' placeholders is good practice as it prevents SQL Injection.
4. The code block runs, but if the cat already exists inside the database, a sqlite3.IntegrityError is returned, indicating the cat's name is already recorded. (better hope you don't have multiple cats with the same name!)
5. It prints a confirmation statement, informing the user that the cat has been added to the database.

So in short: command is run -> passed into SQL INSERT command -> checks for existing entries -> prints confirmation

When the user wants to log their cat's daily metrics using the log command:

command is run → input validated → user confirms → INSERT into log table → prints confirmation

When the user wants an AI-generated health overview using the overview command:

command is run → fetches logs from SQLite → sends to llama-3.3-70b via Groq → streams health overview to terminal

Features

• Contains a log command, which takes in arguments directly from the terminal, or prompts the user for them if some values are not given.
• Look back at how much your cats have changed with the history command and visualize it with graph.
• An overview can be provided of a specific cat, using Llama 3.3 to analyze the .db.
• View saved cats with list-cats and when they were last logged with status.
• Directly modify the database with edit and delete.
• Send the data to someone as a spreadsheet with export.
• Run the CLI in interactive mode, where your commands don't need to be prefixed and runs as it's own proccess.

Setup

Windows:

1. Go to the releases tab and download the latest catalogger-cli.exe. (or self generate the exe.)
2. Save it to a seperate folder, (Optional, but recommended) as the cat-a-log.db, cat_a_log.csv, and .env (explained in AI Overview Setup) all need to be in the same location as catalogger-cli.exe.

Mac/Linux

1. Click the green "Code" button at the top of the repo and click Download ZIP.
2. Make sure Python 3 is installed.
3. Extract the .zip and open a terminal window inside the newly created folder.
4. Create a virtual enviroment: python -m venv .venv
5. Activate it: source .venv/bin/activate
6. Install dependencies: pip install -r requirements.txt
7. Run the CLI: python src/main.py(Note: All files created will be outside the src folder as that is where the terminal is running from)

AI Overview Setup

1. In the same folder where the CLI is being ran from (folder in Windows, terminal running location in Mac/Linux), create a file named .env
2. Go to Groq API Keys, log in and generate your own API key. (Don't share it with anyone)
3. When you copy your key, open .env and add the line API_KEY=[replace with your key]
4. Save .env and rerun the CLI.

Self Packaging

If you want to package the CLI yourself locally as an .exe, you can open the terminal in the main catalogger folder and run these commands with Python installed:

1. pip install pyinstaller
2. pyinstaller --onefile --name catalogger-cli --icon "images/logo.ico" src/main.py

Usage

Example Session

add-entry

Add one of your feline companions to your local database.

Arguments	Explanation	Required
--name	Name of the cat you want to add	YES
--birth	When your cat was born (Best formatted asYYYY-MM-DD)	NO
--breed	Breed of your cat	NO

log

Log health metrics of a specific cat.

(If an argument is not provided when the command is initially run, the CLI will prompt you to insert it via an input box.)

Arguments	Explanation	Required
--cat	Name of the cat you want to log	NO
--weight	Current weight of the cat in kilograms	NO
--activity	How active the cat is on a scale of 1-5	NO
--appetite	How hungry is the cat:None, (N)ormal, (L)ow, (H)igh	NO
--water	How much water does the cat drink:None, (N)ormal, (L)ow, (H)igh	NO
--litter	Litter of the cat:(N)ormal, (S)training, (D)iarrhea, (C)onstipated	NO
--notes	Extra notes the AI can use to better its understanding of the cat's current situation	NO

status

Shows saved cats and when they were last logged.

list-cats

Prints out all cats currently stored in the database alongside their birth dates and breeds.

history

Show metrics of all cats or a specific cat.

Arguments	Explanation	Required
--cat	If not provided, all saved metrics will be returned	NO

graph

Create a graph of your cat's weight over time

Arguments	Explanation	Required
--cat	Choose a cat whose weight will be graphed	YES

edit

Edit an entry of a cat or a log.

Arguments	Explanation	Required
--mode	Edit an entry from thecats table or the log table Accepted arguments: cat, cats, log, logs	YES
--id	Select a row ID to edit. If not provided, possible options will be displayed with their ID's	NO

delete

Deleta an entry of a cat or a log.

Arguments	Explanation	Required
--mode	Delete an entry from thecats table or the log table Accepted arguments: cat, cats, log, logs	YES
--id	Select a row ID to delete. If not provided, possible options will be displayed with their ID's	NO

overview

Uses AI to create a health overview by checking the logged metrics of the cat you selected.

Arguments	Explanation	Required
--cat	The cat you want the AI to provide an overview on	YES

export

Export selected data or the entire database as a .csv

Arguments	Explanation	Required
--cat	If not provided, all data will be exported	NO
--output	Where the.csv should be saved. If not provided, it will save in the same location where the CLI was run.	NO