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

New Issue

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

product-owner commented

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

Problem Statement

Spec F5.2 (terraphim-agent-session-search-spec.md, lines 432-444) defines two distinct entry points for concept-based discovery:

/sessions by-concept "authentication"
/sessions by-concept "OAuth" --connected-to "JWT"

The repository already implements /sessions concepts <concept> (REPL SessionsSubcommand::Concepts in crates/terraphim_agent/src/repl/commands.rs:171) and /sessions related <id>, but neither supports the spec's --connected-to <other-concept> filter, which is the whole point of F5.2: surface sessions where two concepts co-occur, leveraging the rolegraph's concept_connections data already produced by the enrichment pipeline (crates/terraphim_sessions/src/enrichment/). Without this filter, users cannot ask "show me sessions where OAuth is discussed alongside JWT" -- a key knowledge-graph query.

Acceptance Criteria

Add a new REPL subcommand SessionsSubcommand::ByConcept { concept: String, connected_to: Option<String>, limit: Option<usize> } parsed from /sessions by-concept "<concept>" [--connected-to "<other>"] [--limit N]
Implement a service method SessionService::sessions_by_concept(&self, concept: &str, connected_to: Option<&str>, limit: Option<usize>) -> Vec<&Session> in crates/terraphim_sessions/src/service.rs that:
- Without connected_to: returns sessions whose SessionConcepts.concepts contains the given concept (case-insensitive equality on the normalised form)
- With connected_to: returns sessions whose SessionConcepts.concept_connections contains the unordered pair (concept, connected_to) (already computed by the enricher)
Sort results by descending occurrence count of the primary concept, then by updated_at desc
REPL handler renders results as a coloured table (rank, title, source, date, occurrences) matching the existing /sessions concepts output style
Robot mode (--robot --format json) returns a RobotResponse whose data.results[] carries the same fields plus concept, connected_to, and the matching concept_connections list
Aliases: /sessions byconcept (no hyphen) is treated as a typo and auto-corrected by the existing ForgivingParser (no separate aliasing required if Jaro-Winkler covers it)
Unit tests in crates/terraphim_sessions/src/service.rs cover: (a) unfiltered concept lookup, (b) connected_to filter with at least one match, (c) connected_to filter with no match -> empty result
cargo test -p terraphim_sessions passes
cargo test -p terraphim_agent passes
cargo clippy -p terraphim_sessions -p terraphim_agent -- -D warnings passes

Proposed Approach

The enrichment pipeline already populates SessionConcepts { concepts, concept_connections, dominant_topics }. The service method becomes a straightforward filter over the in-memory cache. Normalise input concepts via NormalizedTermValue::from(...) so casing and whitespace differences do not cause misses. Reuse the existing renderer from /sessions concepts and add a single conditional column when connected_to is set. For robot mode, extend the existing SessionConceptsResponse (or introduce SessionsByConceptResponse alongside it).

Crates affected:

crates/terraphim_sessions -- SessionService filter + tests
crates/terraphim_agent -- REPL command parsing, handler dispatch, robot serialisation

Key types/functions to add:

SessionsSubcommand::ByConcept
SessionService::sessions_by_concept
repl::handler::handle_sessions_by_concept
(optional) SessionsByConceptResponse for robot envelope

Dependencies

None. Independent of #12 (/sessions path, concept traversal) and #16 (/sessions analyze). Builds on the already-shipped enrichment pipeline (Phase 3.1).

Verification

cargo test -p terraphim_sessions service::sessions_by_concept
cargo test -p terraphim_agent
cargo clippy -p terraphim_sessions -p terraphim_agent -- -D warnings

Manual REPL:

/sessions by-concept "authentication"
/sessions by-concept "OAuth" --connected-to "JWT"

Both should return ranked sessions; the second should only list sessions whose enrichment recorded the OAuth-JWT pair.

Scope

Single PR, ~250-350 LOC: one new service method, one new REPL subcommand variant + parser, one handler, three unit tests, one robot-mode integration assertion. No new external dependencies.

## Problem Statement Spec F5.2 (terraphim-agent-session-search-spec.md, lines 432-444) defines two distinct entry points for concept-based discovery: ``` /sessions by-concept "authentication" /sessions by-concept "OAuth" --connected-to "JWT" ``` The repository already implements `/sessions concepts <concept>` (REPL `SessionsSubcommand::Concepts` in `crates/terraphim_agent/src/repl/commands.rs:171`) and `/sessions related <id>`, but neither supports the spec's `--connected-to <other-concept>` filter, which is the whole point of F5.2: surface sessions where two concepts co-occur, leveraging the rolegraph's `concept_connections` data already produced by the enrichment pipeline (`crates/terraphim_sessions/src/enrichment/`). Without this filter, users cannot ask "show me sessions where OAuth is discussed alongside JWT" -- a key knowledge-graph query. ## Acceptance Criteria - [ ] Add a new REPL subcommand `SessionsSubcommand::ByConcept { concept: String, connected_to: Option<String>, limit: Option<usize> }` parsed from `/sessions by-concept "<concept>" [--connected-to "<other>"] [--limit N]` - [ ] Implement a service method `SessionService::sessions_by_concept(&self, concept: &str, connected_to: Option<&str>, limit: Option<usize>) -> Vec<&Session>` in `crates/terraphim_sessions/src/service.rs` that: - Without `connected_to`: returns sessions whose `SessionConcepts.concepts` contains the given concept (case-insensitive equality on the normalised form) - With `connected_to`: returns sessions whose `SessionConcepts.concept_connections` contains the unordered pair `(concept, connected_to)` (already computed by the enricher) - [ ] Sort results by descending occurrence count of the primary concept, then by `updated_at` desc - [ ] REPL handler renders results as a coloured table (rank, title, source, date, occurrences) matching the existing `/sessions concepts` output style - [ ] Robot mode (`--robot --format json`) returns a `RobotResponse` whose `data.results[]` carries the same fields plus `concept`, `connected_to`, and the matching `concept_connections` list - [ ] Aliases: `/sessions byconcept` (no hyphen) is treated as a typo and auto-corrected by the existing `ForgivingParser` (no separate aliasing required if Jaro-Winkler covers it) - [ ] Unit tests in `crates/terraphim_sessions/src/service.rs` cover: (a) unfiltered concept lookup, (b) `connected_to` filter with at least one match, (c) `connected_to` filter with no match -> empty result - [ ] `cargo test -p terraphim_sessions` passes - [ ] `cargo test -p terraphim_agent` passes - [ ] `cargo clippy -p terraphim_sessions -p terraphim_agent -- -D warnings` passes ## Proposed Approach The enrichment pipeline already populates `SessionConcepts { concepts, concept_connections, dominant_topics }`. The service method becomes a straightforward filter over the in-memory cache. Normalise input concepts via `NormalizedTermValue::from(...)` so casing and whitespace differences do not cause misses. Reuse the existing renderer from `/sessions concepts` and add a single conditional column when `connected_to` is set. For robot mode, extend the existing `SessionConceptsResponse` (or introduce `SessionsByConceptResponse` alongside it). Crates affected: - `crates/terraphim_sessions` -- `SessionService` filter + tests - `crates/terraphim_agent` -- REPL command parsing, handler dispatch, robot serialisation Key types/functions to add: - `SessionsSubcommand::ByConcept` - `SessionService::sessions_by_concept` - `repl::handler::handle_sessions_by_concept` - (optional) `SessionsByConceptResponse` for robot envelope ## Dependencies None. Independent of #12 (`/sessions path`, concept traversal) and #16 (`/sessions analyze`). Builds on the already-shipped enrichment pipeline (Phase 3.1). ## Verification ``` cargo test -p terraphim_sessions service::sessions_by_concept cargo test -p terraphim_agent cargo clippy -p terraphim_sessions -p terraphim_agent -- -D warnings ``` Manual REPL: ``` /sessions by-concept "authentication" /sessions by-concept "OAuth" --connected-to "JWT" ``` Both should return ranked sessions; the second should only list sessions whose enrichment recorded the OAuth-JWT pair. ## Scope Single PR, ~250-350 LOC: one new service method, one new REPL subcommand variant + parser, one handler, three unit tests, one robot-mode integration assertion. No new external dependencies.

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

product-owner referenced this issue

2026-04-27 07:00:23 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner referenced this issue

2026-04-27 11:04:34 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

root referenced this issue

2026-04-27 13:05:00 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35