feat: /sessions analyze subcommand with dominant-topic analyser (F4.4, Task 3.1.3) #16

New Issue

2026-04-24T11:07:40+02:00

product-owner commented

2026-04-24 11:07:40 +02:00

Problem Statement

The session-search spec (F4.4) lists /sessions analyze --show concepts as a primary command, and Phase 3 Task 3.1.3 requires "dominant topic identification" via frequency analysis and concept clustering. Task 3.3.2 (stats) and 3.3.1 (timeline) exist, but neither surfaces per-session analytics (dominant topics, concept density, code-vs-prose ratio, language breakdown).

Today SessionsSubcommand offers Stats (aggregate), Timeline (temporal), Concepts { concept } (reverse lookup), but no forward analysis on a session or filtered set. Agents cannot answer "what is this session about?" or "what topics dominate my last 7 days of work?" without manually post-processing.

Upstream: spec F4.4 example, F5.1 dominant_topics field, Phase 3 Task 3.1.3 + 3.3.

Acceptance Criteria

Add SessionsSubcommand::Analyze { session_id: Option<String>, show: Option<String>, since: Option<String>, top_n: Option<usize> }
- session_id None = analyse all sessions (subject to --since)
- show one of: concepts (default), languages, files, all
- top_n defaults to 10, max 100
Implement SessionAnalyzer in terraphim_sessions::enrichment that computes:
- Dominant concepts (frequency-sorted, uses existing SessionEnrichment::concepts)
- Language distribution from SessionMetadata::languages
- File reference counts (already available via Files subcommand backend)
Robot mode output: RobotResponse { data: { scope: "session" | "global", session_count, dominant_concepts: [{ concept, occurrences, session_count }], languages: [{ lang, percent }], top_files: [...] } }
Interactive mode renders sorted tables with colour accents
Empty-session-set returns ExitCode::ERROR_NOT_FOUND with suggestion "run /sessions import first"
Unit tests for the analyser (fixture-based, no network)
cargo test -p terraphim_sessions --features enrichment passes
cargo test -p terraphim_agent --features repl-sessions,enrichment passes
cargo clippy -p terraphim_sessions --features enrichment -- -D warnings passes

Proposed Approach

Crates touched: terraphim_sessions (new enrichment/analyzer.rs), terraphim_agent (commands.rs, handler.rs, robot/docs.rs)
Reuse existing SessionEnrichment data; add aggregation functions that fold over a slice
Parse --since identical to /sessions import (jiff Timestamp / civil Date)
Add robot/docs.rs entries so schema + examples are discoverable

Dependencies

Depends on enrichment pipeline being present (already shipped per spec Phase 3 status)
Does NOT block or depend on #12 (/sessions path), #9 (/sessions recommend), #5 (Tantivy) -- it works on the in-memory session set

Verification

cargo test -p terraphim_sessions --features enrichment analyzer
cargo test -p terraphim_agent --features repl-sessions,enrichment sessions_analyze
cargo clippy -p terraphim_sessions --features enrichment -- -D warnings
./target/debug/terraphim-agent --robot sessions analyze --show concepts --top-n 5
./target/debug/terraphim-agent --robot sessions analyze --since 2026-04-01 --show all

Scope

Single PR. ~300-400 lines across analyser + parser + handler + tests.

## Problem Statement The session-search spec (F4.4) lists `/sessions analyze --show concepts` as a primary command, and Phase 3 Task 3.1.3 requires "dominant topic identification" via frequency analysis and concept clustering. Task 3.3.2 (stats) and 3.3.1 (timeline) exist, but neither surfaces per-session analytics (dominant topics, concept density, code-vs-prose ratio, language breakdown). Today `SessionsSubcommand` offers `Stats` (aggregate), `Timeline` (temporal), `Concepts { concept }` (reverse lookup), but no forward analysis on a session or filtered set. Agents cannot answer "what is this session about?" or "what topics dominate my last 7 days of work?" without manually post-processing. Upstream: spec F4.4 example, F5.1 dominant_topics field, Phase 3 Task 3.1.3 + 3.3. ## Acceptance Criteria - [ ] Add `SessionsSubcommand::Analyze { session_id: Option<String>, show: Option<String>, since: Option<String>, top_n: Option<usize> }` - `session_id` None = analyse all sessions (subject to `--since`) - `show` one of: `concepts` (default), `languages`, `files`, `all` - `top_n` defaults to 10, max 100 - [ ] Implement `SessionAnalyzer` in `terraphim_sessions::enrichment` that computes: - Dominant concepts (frequency-sorted, uses existing `SessionEnrichment::concepts`) - Language distribution from `SessionMetadata::languages` - File reference counts (already available via `Files` subcommand backend) - [ ] Robot mode output: `RobotResponse { data: { scope: "session" | "global", session_count, dominant_concepts: [{ concept, occurrences, session_count }], languages: [{ lang, percent }], top_files: [...] } }` - [ ] Interactive mode renders sorted tables with colour accents - [ ] Empty-session-set returns `ExitCode::ERROR_NOT_FOUND` with suggestion "run /sessions import first" - [ ] Unit tests for the analyser (fixture-based, no network) - [ ] `cargo test -p terraphim_sessions --features enrichment` passes - [ ] `cargo test -p terraphim_agent --features repl-sessions,enrichment` passes - [ ] `cargo clippy -p terraphim_sessions --features enrichment -- -D warnings` passes ## Proposed Approach - Crates touched: `terraphim_sessions` (new `enrichment/analyzer.rs`), `terraphim_agent` (commands.rs, handler.rs, robot/docs.rs) - Reuse existing `SessionEnrichment` data; add aggregation functions that fold over a slice - Parse `--since` identical to /sessions import (jiff Timestamp / civil Date) - Add `robot/docs.rs` entries so schema + examples are discoverable ## Dependencies - Depends on enrichment pipeline being present (already shipped per spec Phase 3 status) - Does NOT block or depend on #12 (/sessions path), #9 (/sessions recommend), #5 (Tantivy) -- it works on the in-memory session set ## Verification ``` cargo test -p terraphim_sessions --features enrichment analyzer cargo test -p terraphim_agent --features repl-sessions,enrichment sessions_analyze cargo clippy -p terraphim_sessions --features enrichment -- -D warnings ./target/debug/terraphim-agent --robot sessions analyze --show concepts --top-n 5 ./target/debug/terraphim-agent --robot sessions analyze --since 2026-04-01 --show all ``` ## Scope Single PR. ~300-400 lines across analyser + parser + handler + tests.

product-owner added a new dependency 2026-04-24 11:08:34 +02:00

#14 feat: /sessions import subcommand with --source/--since filters (F4.4, Task 2.6.1)

root referenced this issue

2026-04-24 11:12:24 +02:00

feat: /sessions import subcommand with --source/--since filters (F4.4, Task 2.6.1) #14

product-owner referenced this issue

2026-04-25 03:01:41 +02:00

feat: /sessions by-concept with --connected-to filter (F5.2) #22

product-owner referenced this issue

2026-04-25 04:01:37 +02:00

feat: /sessions cluster --algorithm kmeans --k N for concept-based session grouping (F5.2) #23

root referenced this issue