civiclens 0.5.0

CivicLens AI – civic education and executive document analysis

A Command Line Interface (CLI) is best understood as a simple language you use to tell a computer what to do. Like natural language, it’s structured around verbs (actions), nouns (things), and modifiers (details).

CLI Sentence Structure

• verb [options] noun [arguments] : Do this action, in this way, to this thing, with these details
• cp report.pdf backup/
  • Verb: copy, Noun: source, Noun: destination
• git commit -m "Fix login bug"
  • git (tool), commit (verb), -m (modifier), Argument (message)
• docker run -p 8080:80 nginx
  • docker (tool), run (verb), Modifier + argument, Noun (image)
  • 📖 English: “Run an Nginx container, mapping port 8080 to 80.”

Breaking Down CLI Commands

When reading or writing a command, ask:
  - What action do I want? → Verb
  - On what? → Noun
  - How exactly? → Options / flags
  - With what details? → Arguments

Verb (Command)

• The verb tells the system what action to perform.

Examples:

ls → list
cp → copy
mv → move
rm → remove
git commit → commit changes

Think of verbs as actions.

Noun (Target / Object)

• The noun is what the action is performed on.

Examples:

Files: `file.txt`
Directories: `src/`
Resources: `origin, main, container`

Adjectives / Modifiers (Options & Flags)

• Modifiers change how the verb behaves.
• They usually start with: - (short flag) -- (long flag)

Examples:

-l → long format
-a → include hidden items
--recursive → apply action recursively

Demo

civiclens --help
civiclens --version

civiclens ingest \
    --source s3 \
    --path s3://eo-archive \
    --chunk-size 1200

Example

civiclens query "How does this EO affect education?" --audience teen

civiclens query "How does this executive order affect education?" \
  --audience teen \
  --top-k 5 \
  --show-sources

civiclens prompt "How does this executive order affect education?" \
  --temperature 0.0 \
  --max-tokens 1024 \
  --model "gpt-oss-20b" \
  --url "http://localhost:11434/api/chat"

Example

civiclens eval \
  --dataset benchmarks/eo_questions.json \
  --metrics faithfulness answer_relevance context_recall context_precision \
  --top-k 5 \
  --save-results

Add this to TOML

[project]
name = "civiclens"
version = "0.1.0"
description = "CivicLens AI – civic education and executive document analysis"
requires-python = ">=3.9"

[project.scripts]
civiclens = "civiclens.cli:main"

[tool.uv]
package = true

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

Install

uv pip install -e .

which civiclens


civiclens --help
civiclens query "How does this EO affect education?"
civiclens eval --dataset benchmarks/eo_questions.json

Docker deployment

FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install .

EXPOSE 11434

ENTRYPOINT ["civiclens"]


# To build and run the Docker container 
docker build -t civiclens-app .

# Run
docker run -it civiclens-app --help
docker run -it civiclens-app info
docker run -it civiclens-app query "who won the first world cup in soccer?"
docker run -it civiclens-app  prompt "who won the first world cup in soccer?" -p 11434:11434
# docker run -it civiclens-app eval --dataset benchmarks/eo_questions.json

# Push
docker tag civiclens-app worldbosskafka/civiclens-app:latest

Deploy to PyPI

# Build the package
uv build

# https://pypi.org/
export PYPI_TOKEN=
# Publish
uv publish --username __token__ --password $PYPI_TOKEN

# install 
uv pip install civiclens==0.3.0
pip install civiclens==0.3.0
pip install civiclens