# IKnowledgeService

- File ID: file:pvs6tn:iknowledgeservice-cs
- Path: NexusReader.Application/Abstractions/Services/IKnowledgeService.cs
- Role: service
- Layer: application

## Purpose

Defines the application-level abstraction for knowledge-related operations (semantic search, summarization, QA, groundedness checks, cache management) used by higher-level components.

## Key Details

Application-level abstraction returning FluentResults-wrapped DTOs (KnowledgePacket, GroundedResponseDto, SemanticSearchResultDto). No runtime logic in this file; it defines contracts for knowledge-related orchestration implemented elsewhere.

## Symbols

- IKnowledgeService: Defines the application-level abstraction for knowledge-related operations (semantic search, summarization, QA, groundedness checks, cache management) used by higher-level components.
- GetKnowledgeAsync(): Return a KnowledgePacket for provided text scoped to a tenant and optional ebook.
- GetGraphDataAsync(): Produce graph-structured knowledge data for the given text and tenant context.
- GetKnowledgeMapAsync(): Generate a knowledge map (likely node/edge representation) for the supplied text and tenant.
- GetSummaryAndQuizAsync(): Create a summary and quiz (assessment) artifact for given text within tenant/ebook scope.
- GetRelevantContextAsync(): Retrieve a list of relevant context snippets for a query within a tenant.
- VerifyGroundednessAsync(): Evaluate whether an answer is grounded in provided context and return a score/rationale.
- SearchLibrarySemanticallyAsync(): Perform a semantic search over the library for a tenant and return top results up to a limit.
- AskQuestionAsync(): Ask a question against tenant (and optional ebook) data and return a grounded response, limited by passed limit.
- ClearCacheAsync(): Clear any service-level caches used by the knowledge subsystem.
- GroundednessResult: Represents the outcome of a groundedness check with score, rationale, and boolean flag.

## Dependencies

- No resolved dependencies.

## Calls

- No resolved calls.

## Unresolved References

- dependency-target: FluentResults
- dependency-target: NexusReader.Application.DTOs.AI

## Coverage

- Symbols: 11
- Executable symbols: 9
- Executable symbols with control flow: 9
- Grounded edges: 11
- Unresolved references: 2
- Control-flow fragments: 9
- Unresolved jumps: 0
- Unsupported constructs: 0
- Control-flow coverage: 100%
- Required diagrams: 2
- Generated diagrams: 2

## Control Flow Fragments

- GetKnowledgeAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- GetGraphDataAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- GetKnowledgeMapAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- GetSummaryAndQuizAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- GetRelevantContextAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- VerifyGroundednessAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- SearchLibrarySemanticallyAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- AskQuestionAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
- ClearCacheAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs

## Diagrams

### IKnowledgeService Neighborhood

```mermaid
flowchart LR
    class_utixgx_iknowledgeservice("IKnowledgeService")
    file_pvs6tn_iknowledgeservice_cs("IKnowledgeService")
    method_1ckhg6n_getknowledgeasync[["GetKnowledgeAsync()"]]
    method_1g8j6qo_getgraphdataasync[["GetGraphDataAsync()"]]
    method_1oclqd_verifygroundednessasync[["VerifyGroundednessAsync()"]]
    method_1odjeej_searchlibrarysemanticallyasync[["SearchLibrarySemanticallyAsync()"]]
    method_1yhcrn6_getrelevantcontextasync[["GetRelevantContextAsync()"]]
    method_26njdb_clearcacheasync[["ClearCacheAsync()"]]
    method_7pcmld_getsummaryandquizasync[["GetSummaryAndQuizAsync()"]]
    method_cuqhj0_getknowledgemapasync[["GetKnowledgeMapAsync()"]]
    method_f76by4_askquestionasync[["AskQuestionAsync()"]]
    type_1a84if1_groundednessresult[/"GroundednessResult"/]
```

### IKnowledgeService Execution Overview

```mermaid
flowchart TD
    class_utixgx_iknowledgeservice("IKnowledgeService")
    method_1ckhg6n_getknowledgeasync[["GetKnowledgeAsync()"]]
    method_1g8j6qo_getgraphdataasync[["GetGraphDataAsync()"]]
    method_1oclqd_verifygroundednessasync[["VerifyGroundednessAsync()"]]
    method_1odjeej_searchlibrarysemanticallyasync[["SearchLibrarySemanticallyAsync()"]]
    method_1yhcrn6_getrelevantcontextasync[["GetRelevantContextAsync()"]]
    method_26njdb_clearcacheasync[["ClearCacheAsync()"]]
    method_7pcmld_getsummaryandquizasync[["GetSummaryAndQuizAsync()"]]
    method_cuqhj0_getknowledgemapasync[["GetKnowledgeMapAsync()"]]
    method_f76by4_askquestionasync[["AskQuestionAsync()"]]
    class_utixgx_iknowledgeservice -->|contains| method_1ckhg6n_getknowledgeasync
    class_utixgx_iknowledgeservice -->|contains| method_1g8j6qo_getgraphdataasync
    class_utixgx_iknowledgeservice -->|contains| method_1oclqd_verifygroundednessasync
    class_utixgx_iknowledgeservice -->|contains| method_1odjeej_searchlibrarysemanticallyasync
    class_utixgx_iknowledgeservice -->|contains| method_1yhcrn6_getrelevantcontextasync
    class_utixgx_iknowledgeservice -->|contains| method_26njdb_clearcacheasync
    class_utixgx_iknowledgeservice -->|contains| method_7pcmld_getsummaryandquizasync
    class_utixgx_iknowledgeservice -->|contains| method_cuqhj0_getknowledgemapasync
    class_utixgx_iknowledgeservice -->|contains| method_f76by4_askquestionasync
```

## Diagram Validation

- Status: pass
