Part 5: AI
25. The agent system (optional)#
What it is: a background program called aisystem that takes jobs ("index these files", "find documents about X", "check health"), runs one job at a time, and uses the AI model when a job needs it. It has a small dashboard.
Status: this is a test version. It works only on two test libraries called alpha and beta, which hold made-up files. It does not read your real files, move anything, or recognise faces.
You need: Chapters 18–22 done (the model running on 127.0.0.1:8095), and a copy of the aisystem files (see "Moving it to another server" below).
How it connects#
flowchart LR
Y["You: terminal or<br/>browser via tunnel"] --> API["aisystem<br/>127.0.0.1:8097<br/>(runs as your user)"]
API --> Q[("Job queue")]
Q --> W["One worker<br/>at a time"]
W --> T["Fixed tools:<br/>index, search,<br/>labels, health"]
T --> L[("Test libraries<br/>alpha / beta")]
W -- "only when needed" --> M["AI model<br/>127.0.0.1:8095"]- It listens on
127.0.0.1:8097, so it's reachable only from the server and through an SSH tunnel. - It runs under your own user account as a user service, not as
ai. - It only talks to the model on
127.0.0.1:8095. It has no general shell and no internet tools.
What it can do#
| Job (workflow) | Does | Uses the AI? |
|---|---|---|
index.library |
Lists files, records fingerprints, pulls text out of text files and PDFs | No |
find.documents |
Finds passages in indexed text | Optional, to understand your question |
find.photos |
Finds photos by labels you gave them (e.g. cat, a person's name) |
Optional |
organize.plan |
Suggests folders by type and year, but moves nothing | No |
knowledge.record |
Saves a nickname ("alias") or rule you give it | No |
health.diagnose |
Reports service status and disk space | Optional |
maintenance.run |
Checks its own databases are intact | No |
Where its files are#
~/.local/lib/aisystem/ the program
~/.local/share/aisystem/config.json settings
~/.local/share/aisystem/alpha.access access key for the alpha library (keep private)
~/.local/share/aisystem/state/ job queue
~/.local/share/aisystem/alphacorpus/ alpha's test files
~/.local/share/aisystem/alphastate/ alpha's databases
~/.config/systemd/user/aisystem.service the user service
Check it's running#
systemctl --user is-active aisystem
systemctl --user is-enabled aisystem
loginctl show-user $USER -p Linger
curl -s http://127.0.0.1:8097/health
Expected: active, enabled, Linger=yes, and a short health reply.
Linger means "keep my user services running when I'm logged out, and start them at boot". Without it, aisystem stops when you close SSH.
Give it a job#
All commands start the same way, so first set a shortcut for this terminal session:
cd ~/.local/lib/aisystem
ais() { python3 -m aisystem.cli --config ~/.local/share/aisystem/config.json "$@"; }
Then:
ais submit --owner alpha --workflow index.library --model none 'Index alpha files'
ais submit --owner alpha --workflow find.documents --model none 'Find cobalt sulfate'
ais submit --owner alpha --workflow health.diagnose --model none 'Check health and storage'
Each command puts a job in the queue and returns at once. The work happens in the background. See the results with:
ais status --owner alpha
--model none skips the AI (fast, predictable). --model ministral lets the AI interpret your question first (slower).
partial result after indexing
Normal: images are listed, but reading what's in them isn't built yet.
More examples:
# save a nickname: searching "tenth" will also search "marksheet"
ais submit --owner alpha --workflow knowledge.record --model none --params '{"kind":"alias","key":"tenth","data":{"terms":"marksheet"}}' 'Save alias'
# photos by labels you supplied
ais submit --owner alpha --workflow find.photos --model none 'Find ExamplePerson with cats'
# folder suggestions (moves nothing)
ais submit --owner alpha --workflow organize.plan --model none 'Propose folders'
# check its own databases
ais submit --owner alpha --workflow maintenance.run --model none --params '{"action":"check_catalog"}' 'Check catalog'
# cancel a job (take the job ID from status)
ais cancel --owner alpha JOB-ID
Open the dashboard#
The dashboard only accepts the tunnel on port 18765 on your side, so use exactly this:
ssh -N -L 18765:127.0.0.1:8097 homeserver
Open http://127.0.0.1:18765 in your browser. It asks for an access key. Get it on the server:
cat ~/.local/share/aisystem/alpha.access
Paste it into the page. Don't put it in a URL or share it.
Logs, stop, start#
journalctl --user -u aisystem -n 100 --no-pager
systemctl --user stop aisystem
systemctl --user start aisystem
Stopping aisystem doesn't stop the AI model. That's a separate service (Chapter 21).
Check the program files haven't changed#
cd ~/.local/lib/aisystem
sha256sum -c ~/.local/share/aisystem/release.sha256
Every line should say OK.
Moving it to another server#
aisystem is custom software: there's no package to install it from. Keep a copy of these three things (on your Mac or a backup drive):
mkdir -p ~/aisystem-copy
scp -r homeserver:.local/lib/aisystem ~/aisystem-copy/lib
scp -r homeserver:.local/share/aisystem ~/aisystem-copy/share
scp homeserver:.config/systemd/user/aisystem.service ~/aisystem-copy/
To set it up on a new server (after Chapters 18–22):
scp -r ~/aisystem-copy newserver:
mkdir -p ~/.local/lib ~/.local/share ~/.config/systemd/user
cp -a ~/aisystem-copy/lib ~/.local/lib/aisystem
cp -a ~/aisystem-copy/share ~/.local/share/aisystem
cp ~/aisystem-copy/aisystem.service ~/.config/systemd/user/
chmod 700 ~/.local/share/aisystem
sudo loginctl enable-linger $USER
systemctl --user daemon-reload
systemctl --user enable --now aisystem
Same username
The files may contain the full path of the old home folder (e.g. /home/anish/...). Check with grep -rn /home/ ~/.config/systemd/user/aisystem.service ~/.local/share/aisystem/config.json. On a server with a different username, fix those paths with nano before starting.
Then run "Check it's running" above.
Done when: /health answers, a test job shows a result in ais status, and you have a copy of the three items.
Next: 26. The security layer