dineshkrishna9999/firsttoknow

Purpose and Entry Points

FirstToKnow is a Python 3.11+ terminal application that tracks a developer’s dependencies, repositories, and topics; produces LLM-prioritized tech briefings; and guards new dependencies before git pushes. The executable entry path is src/firsttoknow/__main__.py, delegating command handling to the Typer CLI in src/firsttoknow/cli.py.

CLI Orchestration and Persistent State

The CLI exposes tracking, scanning, briefing, guard, hook-installation, and configuration commands. It is the main boundary between user input and internal workflows. User-selected model settings and tracked items are persisted under the user’s ~/.firsttoknow/ area through src/firsttoknow/config.py; shared domain records and report/severity types live in src/firsttoknow/models.py.

Paths: src/firsttoknow/cli.py, src/firsttoknow/config.py, src/firsttoknow/models.py.

Dependency Discovery and Tracking

scan discovers dependencies from supported project manifests, while explicit track commands add PyPI, npm, GitHub, or topic targets. Scanner output becomes tracked-item state, rather than directly invoking briefing services. This keeps local project inspection separate from remote intelligence gathering.

Paths: src/firsttoknow/scanner.py, src/firsttoknow/cli.py, src/firsttoknow/models.py.

Agent-Driven Briefing Pipeline

brief loads tracked state and runs an ADK-based agent. The agent receives briefing instructions and dynamically selects information-gathering tools; the application does not hardcode a fixed fetch sequence. LiteLLM provides model-provider abstraction, allowing OpenAI, Azure OpenAI, Gemini, Anthropic, or local Ollama models. The resulting synthesis is prioritized into critical, important, and FYI content.

Paths: src/firsttoknow/agents/agent.py, src/firsttoknow/agents/instructions/briefing.py, src/firsttoknow/agents/_tools.py.

External Intelligence and Security Boundary

Agent tools make live calls to PyPI, npm, GitHub, Hacker News, Dev.to, Reddit, and OSV.dev. OSV is the vulnerability authority for CVE lookup; package registries and social/code platforms supply release, repository, and discussion context. Tool implementations are centralized, making remote API behavior a clear boundary from agent reasoning.

Paths: src/firsttoknow/agents/_tools.py, src/firsttoknow/agents/agent.py.

Guard and Git Hook Workflow

The guard examines git diffs for newly introduced dependencies, then evaluates OSV vulnerabilities, license changes, and probable typosquats. An optional LLM review extends this flow to source diffs. Hook support installs/invokes the guard as a pre-push control point, so a risky dependency can be identified before code leaves the local repository.

Paths: src/firsttoknow/guard.py, src/firsttoknow/hooks.py, src/firsttoknow/typosquat.py.

Presentation Runtime

Rich terminal rendering handles progress feedback, formatted Markdown briefings, hyperlinks, status views, and guard-grade reports. It is downstream of both agent and guard workflows and should not own business decisions.

Paths: src/firsttoknow/renderer.py, src/firsttoknow/cli.py.

Runtime and Delivery

The runtime is packaged as a typed Python project under src/firsttoknow/, with dependencies and task definitions in pyproject.toml and poe.toml. Development is container-capable via .devcontainer/, while CI is defined in .github/workflows/ci.yml.