diff --git a/10-prd/behavior/capabilities.md b/10-prd/behavior/capabilities.md index 9f1884f..58d0637 100644 --- a/10-prd/behavior/capabilities.md +++ b/10-prd/behavior/capabilities.md @@ -18,7 +18,17 @@ ## Capability: Semantic retrieval - related claim(s): expose info-base information for retrieval and downstream use; retrieve semantically related info-base entities -- non-goal: semantic retrieval does not generate an answer, create transient information units, silently maintain its index while reading, or imply that feature and graph-navigation retrieval are implemented +- non-goal: semantic retrieval does not generate an answer, create transient information units, silently maintain its index while reading, or subsume feature and graph-navigation retrieval + +## Capability: Lexical feature retrieval + +- related claim(s): expose info-base information for retrieval and downstream use; recall blocks from lexical feature evidence +- non-goal: lexical feature retrieval does not generate an answer, recursively index the graph, replace semantic or graph-navigation retrieval, or imply perceptual/hybrid retrieval is implemented + +## Capability: Media interpretation + +- related claim(s): organize information in one reusable info-base; recall blocks from lexical feature evidence +- non-goal: system-driven interpretation is one additive organization approach; it does not replace faithful Resolver materialization, write retrieval records directly, or define all media organization ## Capability: Focal-block rumination diff --git a/10-prd/behavior/claims.md b/10-prd/behavior/claims.md index c5b5b42..d4f5fe7 100644 --- a/10-prd/behavior/claims.md +++ b/10-prd/behavior/claims.md @@ -52,7 +52,16 @@ - evidence expectation: a real provider embeds graph state collected through ordinary Memos, RSS, Atom, storage, resolver, and organization boundaries; judged primary entities enter the global top three and outrank explicit distractors. - source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/business-and-service-objectives.md` - realization pointers: `../../20-product-tdd/semantic-retrieval-and-peer-capabilities.md`, `../../20-product-tdd/claim-realization-matrix.md` -- impact on existing claims: this realizes semantic retrieval only; feature retrieval, graph-navigation retrieval, answer generation, and Chat InKCre remain independent product capabilities. +- impact on existing claims: this realizes semantic retrieval only; feature retrieval, graph-navigation retrieval, answer generation, and Chat InKCre remain independent product capabilities even when another capability is also implemented. + +## Claim: InKCre recalls blocks from lexical feature evidence + +- claim intent: a person, Agent, or downstream capability should be able to recover an existing block from exact clues remembered from its label, content, metadata, transcript, subtitle, OCR, or useful interpretation. +- evaluation dimensions: one bounded query returns existing blocks with an explainable literal or term-match reason and a plain excerpt; contiguous Chinese fragments do not depend on a Chinese tokenizer; missing or stale derived support is maintained separately from the read. +- evidence expectation: ordinary collected and organized graph state proves exact identifiers, Chinese fragments, metadata-only clues, document bodies, faithful image/audio/video text, and model-authored media interpretation through the same retrieval contract. +- source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/business-and-service-objectives.md` +- realization pointers: `../../20-product-tdd/feature-retrieval-and-media-interpretation.md`, `../../20-product-tdd/claim-realization-matrix.md` +- impact on existing claims: this realizes lexical feature retrieval only; semantic similarity, graph-navigation, perceptual matching, hybrid composition, answer generation, and Chat InKCre remain independent capabilities. ## Claim: InKCre accepts memo-like capture through familiar clients diff --git a/10-prd/behavior/rules-and-invariants.md b/10-prd/behavior/rules-and-invariants.md index c082bf0..87d7b74 100644 --- a/10-prd/behavior/rules-and-invariants.md +++ b/10-prd/behavior/rules-and-invariants.md @@ -36,6 +36,18 @@ - violation impact: block semantics become harder to reason about and downstream use loses clarity. - linked claim(s): organize information in one reusable info-base; expose info-base information for retrieval and downstream use +## Retrieval projections remain derived and independently maintained + +- rationale: lexical records and embeddings accelerate application queries but do not become information authority or a hidden read-time organization path. +- violation impact: a query could mutate graph/index state unexpectedly, stale support could be mistaken for authored truth, or collection/organization ownership could leak into retrieval. +- linked claim(s): expose info-base information for retrieval and downstream use; retrieve semantically related info-base entities; recall blocks from lexical feature evidence + +## Faithful media text and interpretation keep different meaning + +- rationale: transcript, subtitle, and OCR aim to preserve source evidence, while a model-authored description or summary adds an interpretation for later use. +- violation impact: users and downstream capabilities could no longer tell source-derived information from organization-authored meaning, and Resolver materialization would silently acquire organization authority. +- linked claim(s): organize information in one reusable info-base; recall blocks from lexical feature evidence + ## Exact source evidence outranks heuristic duplicate reduction - rationale: stable native identity can justify reconciliation, while content fingerprints and time cutoffs provide weaker and less stable guarantees. diff --git a/10-prd/behavior/workflows.md b/10-prd/behavior/workflows.md index de1504b..136565b 100644 --- a/10-prd/behavior/workflows.md +++ b/10-prd/behavior/workflows.md @@ -48,6 +48,22 @@ - exception flow: unavailable projections and stale records remain absent until explicit maintenance; a missing profile or eligible provider fails explicitly; uncertain post-dispatch outcomes are not replayed automatically - observable outcome: at least one useful existing block or relation is returned under a stated ranking contract without an answer-generation step +## Workflow: Lexical Feature Retrieval + +- actor: a person, Agent, or downstream application capability +- trigger: the actor submits one textual clue remembered from an information unit +- normal flow: the capability compares the clue with fresh Block-local label/text projections and returns a small ranked set of existing blocks with plain excerpts and explicit match evidence +- exception flow: unavailable projections and stale records remain absent until independent maintenance; the query does not repair records or recursively pull text through graph relations +- observable outcome: an existing target block can be recovered from an exact identifier, fragment, metadata clue, document body, faithful media text, or prior interpretation without generating an answer + +## Workflow: System-Driven Media Interpretation + +- actor: organization capability running through a capable peer +- trigger: a typed one-shot job starts, normally after a configured Cron occurrence +- normal flow: the capability selects media blocks still missing an interpretation, routes each modality to its configured Agent, and adds useful interpretation blocks and relations through ordinary graph authority +- exception flow: one unavailable modality, provider failure, or honest no-output result does not block useful independent candidates; completed graph effects remain and the next job derives its candidate set from current graph state +- observable outcome: useful image, audio, or video meaning is added as an explicit interpretation graph that later application capabilities may retrieve + ## Workflow: Focal-Block Rumination - actor: a person or application surface choosing one existing block diff --git a/10-prd/glossary.md b/10-prd/glossary.md index 27a02d3..05077ee 100644 --- a/10-prd/glossary.md +++ b/10-prd/glossary.md @@ -96,6 +96,18 @@ - user-visible or business lifecycle language: finding or navigating information and its context. - notes on ambiguity with framework terms: an application capability may use a sink, index, embedding, or resolver projection without transferring graph authority. +## feature retrieval + +- canonical business meaning: retrieving information from observable features that do not require semantic-similarity ranking or an already-materialized graph path. +- user-visible or business lifecycle language: finding something from a clue remembered about it. +- notes on ambiguity with framework terms: lexical and future perceptual retrieval are feature-retrieval families; graph-navigation owns facts already expressed as graph structure, and hybrid retrieval composes rather than redefines the primitive capabilities. + +## lexical retrieval + +- canonical business meaning: feature retrieval over a block's bounded textual projection, including labels, literal fragments, terms, document text, faithful media text, and explicit interpretations. +- user-visible or business lifecycle language: finding an information unit by a word, phrase, identifier, filename, transcript, subtitle, OCR clue, or description. +- notes on ambiguity with framework terms: lexical retrieval returns existing blocks; it is not Chat, answer generation, recursive graph indexing, or a promise of language-specific tokenization. + ## memo-like capture - canonical business meaning: low-friction collection of thoughts, surrounding events, and small pieces of information through a memo client or collector. diff --git a/20-product-tdd/claim-realization-matrix.md b/20-product-tdd/claim-realization-matrix.md index 5230b4f..442c89f 100644 --- a/20-product-tdd/claim-realization-matrix.md +++ b/20-product-tdd/claim-realization-matrix.md @@ -15,6 +15,7 @@ Map product claims to participating units and clarify each unit's technical resp | Reliably collect RSS and Atom feeds | RSS extension maps bounded RSS 2.0/Atom snapshots to feed, item, enclosure, full-text, and semantic-content graph state | `core-py` | Real-protocol HTTP doubles, PostgreSQL graph acceptance, optional live endpoint smoke, exact replay/update/state/enrichment cases; not a feed-reader product | | Preserve email communication records for later use | Mail extension maps protocol-neutral Mail facts to source, mailbox, canonical email, participant, body, MIME, flag, and reply/reference graph state; remote MIME bytes are materialized lazily | `core-py`; `client-web` as Job peer, info-base navigation host, and resolver consumer | Real Dovecot/IMAP plus PostgreSQL proves ordinary collection, bounded backfill, remote materialization, and built-browser rendering; not a Mail-only inbox or complete email agent | | Accept memo-like capture through familiar clients | Memos extension provides the first memo-family backend access mode | `core-py`; `client-web` for deployment-scoped extension configuration | Backend write/read, comments, attachments, hot credential replacement, hot enable/disable, and graph round-trip | -| Organize information in one reusable info-base | Explicit focal-block rumination is the first admitted organization approach; an Agent may add an ordinary graph interpretation while preserving the focal graph | `core-py`; `client-web` as an explicit trigger surface | Real-provider Resolver/Agent/Tool/graph journey and meaningful no-write boundary; not a complete organization taxonomy, periodic organizer, replacement, merge, or linking realization | -| Expose information for retrieval and downstream use | Semantic retrieval returns one bounded global ranking of existing Blocks/Relations and score metadata; feature and graph-navigation retrieval remain future | `core-py`; `client-web` and future Agent/application consumers | Pinned real Memos/RSS/Atom/HTML/storage corpus, real provider embedding and rumination, four top-three/distractor judgments, local and delegated Peer journeys; not answer generation or Chat InKCre | +| Organize information in one reusable info-base | Explicit focal-block rumination and system-driven media interpretation are admitted organization approaches; Agents may add ordinary graph interpretations while preserving existing graph authority | `core-py`; `client-web` as an explicit rumination trigger and retrieval consumer | Real-provider Resolver/Agent/Tool/graph journeys, meaningful no-write boundary, and bounded independent media candidates; not a complete organization taxonomy, replacement, merge, or linking realization | +| Expose information for retrieval and downstream use | Semantic retrieval ranks existing Blocks/Relations by meaning; lexical feature retrieval recalls existing Blocks from explainable textual clues; graph-navigation and hybrid composition remain independent | `core-py`; `client-web` and future Agent/application consumers | Pinned real multi-source/document/media corpus, real embedding and multimodal providers, local/delegated Peer journeys, and browser List navigation; not answer generation or Chat InKCre | | Retrieve semantically related info-base entities | Resolver/Relation projections feed profile-scoped derived embeddings; one domain facade executes locally or delegates the exact capability to an eligible Peer | `core-py`; `client-web` Peer consumer | Freshness/invalidation/maintenance checks, global Block/Relation ranking, real provider quality gate, exact-target and failover/outcome-unknown protocol cases | +| Recall blocks from lexical feature evidence | Block-local Resolver labels/text feed one derived record per Block; one facade ranks exact/substring/term evidence locally or through an eligible Peer | `core-py`; `client-web` Peer consumer and InfoBaseListView host | Exact identifiers, Chinese fragments, Mail metadata, PDF body, real image/audio/video faithful text, Agent interpretation, freshness/Jobs, delegated Peer, and built-browser navigation | diff --git a/20-product-tdd/cross-unit-contracts.md b/20-product-tdd/cross-unit-contracts.md index 8dbeae7..655a168 100644 --- a/20-product-tdd/cross-unit-contracts.md +++ b/20-product-tdd/cross-unit-contracts.md @@ -46,3 +46,13 @@ Record durable data and behavior contracts that span more than one unit reposito - Peer discovery and invocation remain separate. The generic Peer layer sees exact capability identities and opaque protocol payloads; each business capability keeps its typed request, result, and local execution semantics. + +## Feature Retrieval And Media Interpretation Contract + +- Block-local lexical projection，derived-record maintenance，explainable ranked results， + multimodal AI content parts，faithful Resolver text materialization，system-driven media + interpretation and List-host navigation are owned by the + [Feature Retrieval And Media Interpretation Contract](feature-retrieval-and-media-interpretation.md). +- Resolver materialization and Organization may add graph facts，but the lexical retrieval + owner alone maintains lexical records。Exact synchronous retrieval uses the generic Peer + protocol without giving PeerManager the query or result meaning。 diff --git a/20-product-tdd/feature-retrieval-and-media-interpretation.md b/20-product-tdd/feature-retrieval-and-media-interpretation.md new file mode 100644 index 0000000..33d67df --- /dev/null +++ b/20-product-tdd/feature-retrieval-and-media-interpretation.md @@ -0,0 +1,133 @@ +# Feature Retrieval And Media Interpretation Contract + +## Purpose + +Define the shared semantics of the first feature-retrieval increment: Block-local lexical +projection, independently maintained derived records, exact local/Peer retrieval, faithful +multimodal text materialization, system-driven media interpretation, and client navigation. +Unit repositories still own framework classes, SQL queries, prompts, provider credentials, +storage implementations, UI styling, and runtime scheduling intervals. + +## Retrieval Boundary + +- Feature retrieval uses observable clues that do not require semantic-similarity ranking or + an already-materialized graph path. Lexical and future perceptual retrieval belong to this + family. +- Facts Organization has already expressed as Blocks and Relations remain discoverable + through graph navigation. The same fact may still be recalled lexically while it remains + embedded in one Block-local projection. +- Hybrid retrieval is later composition of primitive retrieval capabilities. It does not + move semantic, lexical, graph-navigation, or perceptual mechanics under one early manager. +- Lexical retrieval returns existing Blocks plus match evidence. It does not create a + transient chunk, generated answer, or second information object. + +## Block-Local Lexical Projection + +```text +Block + exact Resolver -> label + get_text(context="lexical") -> derived record +query ---------------------------------------------------------> ranked existing Blocks +``` + +- One lexical record belongs to one Block and is rebuildable application support. The Block + reference is the record identity; deleting the Block removes the record. +- `label` is a concise Resolver-owned identity. Optional `text` is the Block's bounded lexical + content. A search vector or engine index is derived from those fields and is not a second + graph or content authority. +- `context="lexical"` is a stable cross-peer Resolver vocabulary. It is Block-local and + non-recursive: a parent does not copy a child's complete text merely because a Relation + makes it reachable. Independently useful child Blocks receive their own records. +- Retrieval and maintenance do not read raw `block.content` as a generic fallback. Hydration, + solved-content interpretation, local graph requirements, and permitted faithful + materialization stay behind the exact Resolver contract. +- Unknown/unsupported projection, no meaningful lexical text, authored empty content, and + projection failure remain distinguishable outcomes. One unavailable Block does not stop a + bounded maintenance scan. + +## Maintenance And Ranking + +- Maintenance and retrieval are separate operations. Retrieval never repairs a record or + materializes media as a hidden read effect. +- Maintain scans absent or stale Block records; rebuild additionally selects records older + than its invocation cutoff. Projection happens outside long database transactions and + complete records are upserted in short transactions. +- The exact typed Job identities are + `core.feature_retrieval.lexical.maintain.v1`, + `core.feature_retrieval.lexical.rebuild.v1`, + `core.semantic_retrieval.maintain.v1`, and + `core.semantic_retrieval.rebuild.v1`. Their handlers call the same domain operations used + by explicit execution; Cron creates ordinary Job commands and no second maintenance path. +- Lexical V1 ranks exact label, label substring, text substring, then plain term evidence. + Results expose the existing Block, label, bounded plain excerpt, evidence class, and a + numeric rank. The result limit is at most 20 and there is no pagination. +- Contiguous literal matching supports Chinese fragments without claiming Chinese + segmentation. V1 makes no language-specific tokenizer promise. + +## Faithful Media Materialization + +- Image, audio, and video Resolvers may materialize missing source-faithful `text`, + `transcript`, or `subtitle` child Blocks under their exact contracts. Each information role + remains a separate Relation; a parent lexical record does not copy the child's full text. +- Resolver-owned materialization may use an exact deployment-selected AI Model. Model + selection, prompt, information role, and graph write remain with the Resolver; AI execution + stays graph-blind and performs no automatic model fallback. +- Missing, disabled, dangling, incapable, or provider-rejected model execution makes only the + exact derivation unavailable. Source-native text and other independent roles remain usable. +- Storage supplies actual hydrated bytes. It may additionally expose a transfer URL as an + optional transport hint, but that URL is not content authority or a public-access promise. + +## Canonical Multimodal AI Contract + +- Canonical Chat user messages contain an ordered non-empty sequence of text, image, audio, + or video content parts. Media parts carry actual bytes, standard MIME, and an optional + transfer URL; they never carry Block, Storage, Resolver solved-content, or provider-wire + references. +- AI Model and exact dialect support jointly determine capability, input modalities, output + modalities, and features such as tool calling before provider execution. +- Dialect adapters alone translate canonical parts to provider fields, base64, URL, streaming + deltas, and complete Assistant messages. Shared SDK code does not merge protocol identity. +- `core.openai-compatible.v1` retains its admitted standard subset. + `core.alibaba-model-studio.v1` is the exact adapter for Alibaba Model Studio's multimodal + Chat extensions, including video. Provider-specific fields do not leak into the generic + dialect contract. + +## System-Driven Media Interpretation + +- Media interpretation is an Organization approach because it adds model-authored meaning to + information already in the info-base. It is not faithful Resolver materialization and does + not write lexical records. +- Exact Job `core.organization.media_interpretation.v1` has an empty parameter object. Each + execution derives a bounded set of image/audio/video Blocks currently missing an + `interpretation` result, then selects an independent deployment-configured Agent for each + candidate modality. +- The Agent receives bounded graph context plus one canonical media content part and may add + an interpretation only through its ordinary validated graph Tool. It may honestly produce + no graph. +- Completed interpretation graphs are progress even if the Job times out or another + candidate fails. A later Job derives its candidate set from current graph state; Job does + not own a cursor, checkpoint, attempt ledger, retry, or interpretation-freshness proof. +- Lexical maintenance later indexes the resulting text Blocks. This temporal composition + does not transfer record ownership to Organization. + +## Peer Capability And Client Navigation + +- Exact synchronous capability `core.feature_retrieval.lexical.v1` accepts one non-empty + textual query plus a result bound and returns the V1 lexical result. The business facade + executes locally when available or delegates through the shared Peer contract; a provider + inbound always calls a non-delegating local path. +- `route_to_peer` / `routeToPeer` remains caller-local routing policy and does not enter the + capability payload. +- `InfoBaseListView` is the first list navigation host for retrieval results. Selecting a + result uses the client-supplied singleton `InfoBaseRouter`; List and Graph views may both + realize Block Inspector and solved-content popup destinations without creating another + navigation/history authority. +- Match excerpts are plain presentation-neutral text. A client must not interpret authored + markup merely because it appears in a lexical result. + +## Explicit Non-Goals + +- perceptual matching, hybrid fusion, or graph-navigation implementation +- Relation lexical records or recursive graph indexing +- answer generation, Chat InKCre, or retrieval-owned organization +- language-specific tokenization guarantees +- ANN/HNSW, pagination, million-row performance claims, or an engine-specific query API +- public guest/read-only admission or provider-specific deployment mechanics diff --git a/20-product-tdd/knowledge-capability-contract.md b/20-product-tdd/knowledge-capability-contract.md index 23d35f9..61321c6 100644 --- a/20-product-tdd/knowledge-capability-contract.md +++ b/20-product-tdd/knowledge-capability-contract.md @@ -35,6 +35,10 @@ source-native input -> collection ---------+ [Semantic Retrieval And Peer Capabilities](semantic-retrieval-and-peer-capabilities.md); it does not redefine organization as rumination or imply that the other retrieval modes are implemented. +- The first feature-retrieval increment and system-driven media interpretation live in + [Feature Retrieval And Media Interpretation](feature-retrieval-and-media-interpretation.md). + Lexical records remain application support，faithful media text remains Resolver-owned，and + model-authored interpretation remains Organization-owned even when they compose over time。 ## Graph, Content, And Authority diff --git a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md index f975b99..2186e5c 100644 --- a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md +++ b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md @@ -50,8 +50,9 @@ directed Relation projection -+ timestamps. - These checks are best-effort database-row freshness. Storage-backed bytes may change without updating a Block row, so the contract does not claim universal content freshness. -- Periodic execution may call the same maintenance operation, but it does not create a second - indexing path, generic job table, retry contract, or dirty-state authority. +- Exact typed Jobs may call the same maintenance operation, and Cron may create those Jobs as + ordinary commands. This does not create a second indexing path, retry contract, or + dirty-state authority. ## Ranked Retrieval @@ -137,6 +138,7 @@ response = { status: integer, The first admitted exact capability IDs are: - `core.semantic_retrieval.v1`; +- `core.feature_retrieval.lexical.v1`; - `core.organization.rumination.v1`; - `core.extension.management.v1`; - `extensions.mail.mime_part.materialize.v1`. @@ -158,5 +160,5 @@ The first admitted exact capability IDs are: - generic service registry, capability invocation endpoint, or delegation job - readiness discovery, routing weights, priorities, stickiness, or circuit breakers - persistent Agent Thread/checkpoint storage or Agent-owned exactly-once execution -- feature retrieval, graph-navigation retrieval, answer generation, or Chat InKCre behavior +- graph-navigation retrieval, answer generation, or Chat InKCre behavior - transient chunk/segment persistence, ANN/HNSW, pagination, or cross-profile score fusion diff --git a/20-product-tdd/system-state-and-authority.md b/20-product-tdd/system-state-and-authority.md index 74812ce..7cc4070 100644 --- a/20-product-tdd/system-state-and-authority.md +++ b/20-product-tdd/system-state-and-authority.md @@ -40,6 +40,10 @@ Record durable ownership of authoritative state across units and distinguish it contracts. Profile-scoped Block/Relation embedding records are rebuildable application support; their timestamps express database-row compatibility rather than universal storage-byte freshness. +- Block lexical records are rebuildable application support owned by lexical retrieval. Their + label/text/search projection is Block-local and derived; faithful media text and + Organization-authored interpretation become authoritative only as ordinary graph Blocks + and Relations before later lexical maintenance observes them. - Block row timestamps describe persistence. Source-authored creation or update time remains a content fact owned by the relevant canonical contract. diff --git a/20-product-tdd/unit-topology.md b/20-product-tdd/unit-topology.md index 0d5f0fa..e2bb98e 100644 --- a/20-product-tdd/unit-topology.md +++ b/20-product-tdd/unit-topology.md @@ -36,3 +36,6 @@ Define cross-unit technical boundaries and ownership so changes do not leak resp boundaries, not a terminal-user or graph-ownership boundary. - Semantic retrieval and synchronous capability delegation use the shared [Semantic Retrieval And Peer Capability Contract](semantic-retrieval-and-peer-capabilities.md). +- Lexical feature retrieval，multimodal AI content transport，faithful media materialization， + Organization media interpretation and List-host navigation use the shared + [Feature Retrieval And Media Interpretation Contract](feature-retrieval-and-media-interpretation.md). diff --git a/docs/index.md b/docs/index.md index d7fc2b6..461eb80 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ - [Cross-unit contracts](../20-product-tdd/cross-unit-contracts.md) - [Knowledge capability contract](../20-product-tdd/knowledge-capability-contract.md) - [Semantic retrieval and Peer capabilities](../20-product-tdd/semantic-retrieval-and-peer-capabilities.md) +- [Feature retrieval and media interpretation](../20-product-tdd/feature-retrieval-and-media-interpretation.md) - [Peer database runtime contract](../20-product-tdd/peer-database-runtime-contract.md) - [Claim realization matrix](../20-product-tdd/claim-realization-matrix.md) - [Hub/Spoke ownership profile](../00-meta/submodule-profile.md)