Skip to content

Commit 8660f5b

Browse files
PipDscvrPipDscvr
authored
feat: enforce retrieval relevance thresholds (#2)
1 parent feb218a commit 8660f5b

41 files changed

Lines changed: 1975 additions & 146 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ EMBEDDING_DIMENSIONS=1024
3232
# --- Internal retrieval tuning ---
3333
# Defaults mirror the balanced adaptive policy. These are experimental knobs
3434
# for benchmark sweeps and should not be treated as stable product config.
35+
# Normalized fallback relevance floor for unscoped simple/medium non-temporal searches.
36+
# SIMILARITY_THRESHOLD=0.3
3537
# ADAPTIVE_SIMPLE_LIMIT=5
3638
# ADAPTIVE_MEDIUM_LIMIT=5
3739
# ADAPTIVE_COMPLEX_LIMIT=8

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ node_modules/
1010
.env.local
1111
.env.*.local
1212
.env.test
13+
.mcp.json
1314

1415
# IDE files
1516
.vscode/

‎openapi.json‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3560,6 +3560,12 @@
35603560
"source_site": {
35613561
"type": "string"
35623562
},
3563+
"threshold": {
3564+
"description": "Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging.",
3565+
"maximum": 1,
3566+
"minimum": 0,
3567+
"type": "number"
3568+
},
35633569
"token_budget": {
35643570
"maximum": 50000,
35653571
"minimum": 100,
@@ -3696,12 +3702,32 @@
36963702
"description": "Memory metadata persisted on the row, including caller-supplied verbatim metadata (set via /v1/memories/ingest/quick with skip_extraction=true) and core-generated metadata (e.g. cmo_id, memberMemoryIds, headline). Mirrors the shape /v1/memories/list and /v1/memories/:id return.",
36973703
"type": "object"
36983704
},
3705+
"ranking_score": {
3706+
"description": "Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.",
3707+
"type": [
3708+
"number",
3709+
"null"
3710+
]
3711+
},
3712+
"relevance": {
3713+
"description": "Normalized relevance value used for threshold filtering; clamped to the [0,1] range.",
3714+
"type": [
3715+
"number",
3716+
"null"
3717+
]
3718+
},
36993719
"score": {
37003720
"type": [
37013721
"number",
37023722
"null"
37033723
]
37043724
},
3725+
"semantic_similarity": {
3726+
"type": [
3727+
"number",
3728+
"null"
3729+
]
3730+
},
37053731
"similarity": {
37063732
"type": [
37073733
"number",
@@ -3836,9 +3862,94 @@
38363862
},
38373863
"type": "array"
38383864
},
3865+
"filter_decisions": {
3866+
"description": "Per-candidate threshold decisions emitted only when retrieval tracing is enabled. Entries include per-result source_site, source_kind, and namespace for debugging disclosure scope.",
3867+
"items": {
3868+
"properties": {
3869+
"decision": {
3870+
"enum": [
3871+
"kept",
3872+
"filtered"
3873+
],
3874+
"type": "string"
3875+
},
3876+
"id": {
3877+
"type": "string"
3878+
},
3879+
"namespace": {
3880+
"type": [
3881+
"string",
3882+
"null"
3883+
]
3884+
},
3885+
"ranking_score": {
3886+
"description": "Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.",
3887+
"type": "number"
3888+
},
3889+
"reason": {
3890+
"type": "string"
3891+
},
3892+
"relevance": {
3893+
"description": "Normalized relevance value used for threshold filtering; clamped to the [0,1] range.",
3894+
"type": "number"
3895+
},
3896+
"semantic_similarity": {
3897+
"type": "number"
3898+
},
3899+
"source_kind": {
3900+
"enum": [
3901+
"integration",
3902+
"local"
3903+
],
3904+
"type": "string"
3905+
},
3906+
"source_site": {
3907+
"type": "string"
3908+
},
3909+
"threshold": {
3910+
"type": [
3911+
"number",
3912+
"null"
3913+
]
3914+
}
3915+
},
3916+
"required": [
3917+
"id",
3918+
"source_site",
3919+
"source_kind",
3920+
"namespace",
3921+
"semantic_similarity",
3922+
"ranking_score",
3923+
"relevance",
3924+
"threshold",
3925+
"decision",
3926+
"reason"
3927+
],
3928+
"type": "object"
3929+
},
3930+
"type": "array"
3931+
},
3932+
"filtered_candidate_ids": {
3933+
"items": {
3934+
"type": "string"
3935+
},
3936+
"type": "array"
3937+
},
38393938
"query_text": {
38403939
"type": "string"
38413940
},
3941+
"relevance_filter_reason": {
3942+
"type": "string"
3943+
},
3944+
"relevance_filter_source": {
3945+
"type": "string"
3946+
},
3947+
"relevance_threshold": {
3948+
"type": [
3949+
"number",
3950+
"null"
3951+
]
3952+
},
38423953
"skip_repair": {
38433954
"type": "boolean"
38443955
},
@@ -4091,6 +4202,12 @@
40914202
"source_site": {
40924203
"type": "string"
40934204
},
4205+
"threshold": {
4206+
"description": "Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging.",
4207+
"maximum": 1,
4208+
"minimum": 0,
4209+
"type": "number"
4210+
},
40944211
"token_budget": {
40954212
"maximum": 50000,
40964213
"minimum": 100,
@@ -4227,12 +4344,32 @@
42274344
"description": "Memory metadata persisted on the row, including caller-supplied verbatim metadata (set via /v1/memories/ingest/quick with skip_extraction=true) and core-generated metadata (e.g. cmo_id, memberMemoryIds, headline). Mirrors the shape /v1/memories/list and /v1/memories/:id return.",
42284345
"type": "object"
42294346
},
4347+
"ranking_score": {
4348+
"description": "Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.",
4349+
"type": [
4350+
"number",
4351+
"null"
4352+
]
4353+
},
4354+
"relevance": {
4355+
"description": "Normalized relevance value used for threshold filtering; clamped to the [0,1] range.",
4356+
"type": [
4357+
"number",
4358+
"null"
4359+
]
4360+
},
42304361
"score": {
42314362
"type": [
42324363
"number",
42334364
"null"
42344365
]
42354366
},
4367+
"semantic_similarity": {
4368+
"type": [
4369+
"number",
4370+
"null"
4371+
]
4372+
},
42364373
"similarity": {
42374374
"type": [
42384375
"number",
@@ -4367,9 +4504,94 @@
43674504
},
43684505
"type": "array"
43694506
},
4507+
"filter_decisions": {
4508+
"description": "Per-candidate threshold decisions emitted only when retrieval tracing is enabled. Entries include per-result source_site, source_kind, and namespace for debugging disclosure scope.",
4509+
"items": {
4510+
"properties": {
4511+
"decision": {
4512+
"enum": [
4513+
"kept",
4514+
"filtered"
4515+
],
4516+
"type": "string"
4517+
},
4518+
"id": {
4519+
"type": "string"
4520+
},
4521+
"namespace": {
4522+
"type": [
4523+
"string",
4524+
"null"
4525+
]
4526+
},
4527+
"ranking_score": {
4528+
"description": "Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.",
4529+
"type": "number"
4530+
},
4531+
"reason": {
4532+
"type": "string"
4533+
},
4534+
"relevance": {
4535+
"description": "Normalized relevance value used for threshold filtering; clamped to the [0,1] range.",
4536+
"type": "number"
4537+
},
4538+
"semantic_similarity": {
4539+
"type": "number"
4540+
},
4541+
"source_kind": {
4542+
"enum": [
4543+
"integration",
4544+
"local"
4545+
],
4546+
"type": "string"
4547+
},
4548+
"source_site": {
4549+
"type": "string"
4550+
},
4551+
"threshold": {
4552+
"type": [
4553+
"number",
4554+
"null"
4555+
]
4556+
}
4557+
},
4558+
"required": [
4559+
"id",
4560+
"source_site",
4561+
"source_kind",
4562+
"namespace",
4563+
"semantic_similarity",
4564+
"ranking_score",
4565+
"relevance",
4566+
"threshold",
4567+
"decision",
4568+
"reason"
4569+
],
4570+
"type": "object"
4571+
},
4572+
"type": "array"
4573+
},
4574+
"filtered_candidate_ids": {
4575+
"items": {
4576+
"type": "string"
4577+
},
4578+
"type": "array"
4579+
},
43704580
"query_text": {
43714581
"type": "string"
43724582
},
4583+
"relevance_filter_reason": {
4584+
"type": "string"
4585+
},
4586+
"relevance_filter_source": {
4587+
"type": "string"
4588+
},
4589+
"relevance_threshold": {
4590+
"type": [
4591+
"number",
4592+
"null"
4593+
]
4594+
},
43734595
"skip_repair": {
43744596
"type": "boolean"
43754597
},

0 commit comments

Comments
 (0)