notii 1.0.0

A contacts and notes manager for your terminal

Notii

Your personal terminal assistant — contacts, notes, and tags, all in one place.

Notii is a lightweight command-line tool for managing contacts and notes without ever leaving your terminal. Store a full address book — name, phones, e-mail, birthday, address — and a searchable notebook of tagged notes. Everything is saved automatically between sessions, no database or cloud account required.

---

Features

Contacts

• Add a contact with full name, phone number, e-mail, birthday, and address
• Search contacts across all fields by a text query
• Edit any field of an existing contact
• Delete a contact
• View contacts whose birthday falls within a given number of days

Notes

• Create notes with a title and a free-text body
• Search notes by their text content
• Edit a note's title or body
• Delete notes
• Attach keyword tags to notes
• Search notes by tag and sort alphabetically by tag

General

• Phone numbers and e-mail addresses are validated on entry; invalid values are rejected with a clear message and the prompt is repeated
• Data is persisted automatically to the data/ folder at the project root
• Tab-autocomplete and command history via prompt_toolkit
• All commands use a / prefix; any input without a leading / is rejected with a friendly error

---

Validation rules

Phone numbers — 10–15 digits, optional leading +. Spaces, hyphens, dots, and parentheses are stripped before checking, so 099 123-45-67 and 0991234567 are treated as the same number. Enter multiple phones comma-separated on one prompt.

E-mail — standard [e-mail] format.

Birthday — DD.MM.YYYY format; must be a past date (future dates are rejected). The days counter shows how many days remain until the next annual celebration of that date — the birth year is used only to store the date, not to compute the count.

Tags — letters, digits, underscores _, and hyphens - only; no spaces; 1–50 characters. A leading # is accepted and stripped automatically. Enter multiple tags comma-separated on the /add-tag or /remove-tag prompt.

Name — non-empty, max 100 characters.

Address — non-empty, max 200 characters.

---

Requirements

Python 3.10 or later.

---

Installation

From PyPI

pip install notii

From source

git clone https://github.com/Serhii2009/smart-assistant-cli.git
cd smart-assistant-cli
pip install -r requirements.txt
pip install -e .

---

Running

notii

The application starts, shows a short header, and waits for commands. Type / to see the full command list with autocomplete.

---

Commands

All commands use a / prefix. After entering a command, the application guides you through each required field on a separate prompt line. No arguments are ever typed on the same line as the command itself.

Command	Description
/add-contact	Add a new contact (interactive field prompts)
/show-contacts	List all contacts
/find-contact	Search contacts by any field
/edit-contact	Edit a field of an existing contact
/delete-contact	Delete a contact
/birthdays	Contacts with a birthday in the next N days
/add-note	Create a new note (interactive)
/show-notes	List all notes
/find-note	Search notes by title or body
/edit-note	Edit a note's title or body
/delete-note	Delete a note
/add-tag	Attach a tag to a note
/remove-tag	Remove a tag from a note
/find-by-tag	Find notes by tag
/sort-by-tags	List notes sorted alphabetically by tag
/help	Show the command list
/exit	Save data and exit

/sort-by-tags orders notes alphabetically by their first tag. Notes with no tags appear at the bottom of the list. The first tag on each note is the sort key — add tags in the order you want them.

---

Project structure

smart-assistant-cli/
├── data/
│   ├── contacts.pkl     address book (created automatically on first run)
│   └── notes.pkl        notes (created automatically on first run)
├── src/
│   ├── __init__.py      package version
│   ├── __main__.py      entry point
│   ├── cli.py           REPL loop and command dispatch
│   ├── fields.py        Field base class and all field types
│   ├── contact.py       Record and AddressBook classes
│   ├── note.py          Note and NoteBook classes
│   ├── repository.py    pickle persistence (the only file touching disk)
│   ├── handlers.py      pure handler functions (no I/O)
│   └── renderer.py      all terminal output (the only file using rich)
├── requirements.txt
├── pyproject.toml
└── README.md

Layered architecture:

cli.py  →  handlers.py  →  contact.py / note.py / fields.py
  ↓                                ↓
renderer.py             repository.py

• handlers.py contains only pure functions: no printing, no input
• renderer.py is the only file that imports rich
• repository.py is the only file that reads or writes files
• fields.py is the single source of truth for every validation rule — no field format is checked anywhere else in the codebase

---

Contributing

1. Clone the repository:

   git clone https://github.com/Serhii2009/smart-assistant-cli.git
   cd smart-assistant-cli
   

2. Create a branch for your work:

   git checkout -b feature/your-feature-name
   

3. Install dependencies:

   pip install -r requirements.txt
   pip install -e .
   

4. Make your changes, commit them, and open a pull request against main.

Branch naming conventions: feature/, fix/, docs/.

---

License

MIT — see LICENSE.