minemos 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- minemos/__init__.py +72 -0
- minemos/resolution/__init__.py +186 -0
- minemos/resolution/bridge.py +160 -0
- minemos/resolution/config.py +114 -0
- minemos/resolution/contracts.py +843 -0
- minemos/resolution/host.py +474 -0
- minemos/resolution/identity.py +840 -0
- minemos/resolution/ingest.py +240 -0
- minemos/resolution/interpret.py +1758 -0
- minemos/resolution/language.py +295 -0
- minemos/resolution/lexicon.py +634 -0
- minemos/resolution/native.py +367 -0
- minemos/resolution/normalize.py +514 -0
- minemos/resolution/pipeline.py +312 -0
- minemos/resolution/relationships.py +380 -0
- minemos/resolution/schema.json +257 -0
- minemos/resolution/schema.py +142 -0
- minemos/resolution/segments.py +119 -0
- minemos/resolution/shadow.py +160 -0
- minemos/resolution/similarity.py +221 -0
- minemos/semantic.py +388 -0
- minemos-0.1.0.dist-info/METADATA +472 -0
- minemos-0.1.0.dist-info/RECORD +55 -0
- minemos-0.1.0.dist-info/WHEEL +5 -0
- minemos-0.1.0.dist-info/licenses/LICENSE +202 -0
- minemos-0.1.0.dist-info/licenses/NOTICE +20 -0
- minemos-0.1.0.dist-info/top_level.txt +2 -0
- minemos_engine/__init__.py +29 -0
- minemos_engine/answer.py +60 -0
- minemos_engine/black_hole_memory.py +5160 -0
- minemos_engine/checkpoint.py +1026 -0
- minemos_engine/eligibility.py +403 -0
- minemos_engine/encoders.py +146 -0
- minemos_engine/evidence.py +895 -0
- minemos_engine/intelligence/__init__.py +0 -0
- minemos_engine/intelligence/addressing.py +524 -0
- minemos_engine/intelligence/bm25.py +677 -0
- minemos_engine/intelligence/consolidation.py +90 -0
- minemos_engine/intelligence/dense.py +435 -0
- minemos_engine/intelligence/nli.py +330 -0
- minemos_engine/intelligence/retention.py +169 -0
- minemos_engine/intelligence/utility.py +520 -0
- minemos_engine/intelligence/verification.py +171 -0
- minemos_engine/intelligence/verification_terms.py +393 -0
- minemos_engine/memory_state.py +255 -0
- minemos_engine/memory_update.py +127 -0
- minemos_engine/recall.py +54 -0
- minemos_engine/retrieval/__init__.py +66 -0
- minemos_engine/retrieval/adapter.py +270 -0
- minemos_engine/retrieval/config.py +125 -0
- minemos_engine/retrieval/incremental.py +471 -0
- minemos_engine/retrieval/qdrant.py +973 -0
- minemos_engine/retrieval/qdrant_config.py +197 -0
- minemos_engine/retrieval/snapshot.py +841 -0
- minemos_engine/structured_candidate.py +101 -0
minemos/__init__.py
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"""MINEMOS — persistent memory intelligence for AI applications.
|
|
2
|
+
|
|
3
|
+
Public developer surface:
|
|
4
|
+
|
|
5
|
+
from minemos import BlackHoleMemory, Candidate
|
|
6
|
+
|
|
7
|
+
``BlackHoleMemory`` is imported lazily so that ``import minemos`` stays cheap;
|
|
8
|
+
the first attribute access loads the engine and its encoder models.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from minemos_engine.memory_state import MemoryState, MemorySlot
|
|
12
|
+
from minemos_engine.structured_candidate import Candidate
|
|
13
|
+
from minemos_engine.answer import ANSWER_STATUSES, answer_contract
|
|
14
|
+
from minemos_engine.retrieval import (
|
|
15
|
+
QdrantConfig,
|
|
16
|
+
RetrievalConfig,
|
|
17
|
+
RetrievalConfigurationError,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
try:
|
|
21
|
+
from importlib.metadata import version as _distribution_version
|
|
22
|
+
__version__ = _distribution_version("minemos")
|
|
23
|
+
except Exception: # running from a checkout before installation
|
|
24
|
+
__version__ = "0.1.0"
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"BlackHoleMemory",
|
|
28
|
+
"Candidate",
|
|
29
|
+
"MemoryState",
|
|
30
|
+
"MemorySlot",
|
|
31
|
+
"QdrantConfig",
|
|
32
|
+
"RetrievalConfig",
|
|
33
|
+
"RetrievalConfigurationError",
|
|
34
|
+
"ANSWER_STATUSES",
|
|
35
|
+
"answer_contract",
|
|
36
|
+
"ResolutionConfig",
|
|
37
|
+
"ResolutionRecord",
|
|
38
|
+
"Resolver",
|
|
39
|
+
"ShadowRunner",
|
|
40
|
+
"SourceMessage",
|
|
41
|
+
"EngineSink",
|
|
42
|
+
"SemanticIngestionError",
|
|
43
|
+
"SemanticIngestionReport",
|
|
44
|
+
"SemanticIngestor",
|
|
45
|
+
"ServiceSink",
|
|
46
|
+
"__version__",
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
_RESOLUTION_EXPORTS = frozenset({
|
|
50
|
+
"ResolutionConfig", "ResolutionRecord", "Resolver", "ShadowRunner",
|
|
51
|
+
"SourceMessage",
|
|
52
|
+
})
|
|
53
|
+
|
|
54
|
+
_SEMANTIC_EXPORTS = frozenset({
|
|
55
|
+
"EngineSink", "SemanticIngestionError", "SemanticIngestionReport",
|
|
56
|
+
"SemanticIngestor", "ServiceSink",
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def __getattr__(name: str):
|
|
61
|
+
if name == "BlackHoleMemory":
|
|
62
|
+
from minemos_engine.black_hole_memory import BlackHoleMemory
|
|
63
|
+
return BlackHoleMemory
|
|
64
|
+
if name in _RESOLUTION_EXPORTS:
|
|
65
|
+
from minemos import resolution
|
|
66
|
+
|
|
67
|
+
return getattr(resolution, name)
|
|
68
|
+
if name in _SEMANTIC_EXPORTS:
|
|
69
|
+
from minemos import semantic
|
|
70
|
+
|
|
71
|
+
return getattr(semantic, name)
|
|
72
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
"""Semantic resolution layer: four deterministic stages in front of MINEMOS.
|
|
2
|
+
|
|
3
|
+
raw message
|
|
4
|
+
→ Stage 1 normalize_text / detect_language
|
|
5
|
+
→ Stage 2 interpret
|
|
6
|
+
→ Stage 3 resolve_identity
|
|
7
|
+
→ Stage 4 classify_relationships
|
|
8
|
+
→ minemos.resolution/1 record
|
|
9
|
+
|
|
10
|
+
The layer is candidate-only. It never writes canonical memory, never changes
|
|
11
|
+
retrieval and never consolidates: MINEMOS keeps every memory decision. The
|
|
12
|
+
default mode is ``shadow``; handing candidates to the engine requires the
|
|
13
|
+
explicit ``active`` opt-in in :mod:`minemos.resolution.bridge`.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from .bridge import (
|
|
17
|
+
BridgeDecision,
|
|
18
|
+
absorb_record,
|
|
19
|
+
candidates_for,
|
|
20
|
+
decide,
|
|
21
|
+
eligibility_counts,
|
|
22
|
+
subject_text,
|
|
23
|
+
)
|
|
24
|
+
from .config import ACTIVE_WARNING, DEFAULT_CONFIG, MODES, ResolutionConfig
|
|
25
|
+
from .contracts import (
|
|
26
|
+
ATTRIBUTION_SCOPES,
|
|
27
|
+
ATTRIBUTION_STATUSES,
|
|
28
|
+
ENTITY_TYPES,
|
|
29
|
+
RELATIONSHIP_LABELS,
|
|
30
|
+
STAGE_NAMES,
|
|
31
|
+
SUBJECT_KINDS,
|
|
32
|
+
Attribution,
|
|
33
|
+
Entity,
|
|
34
|
+
Evidence,
|
|
35
|
+
FactCandidate,
|
|
36
|
+
IdentityTransition,
|
|
37
|
+
LanguageInfo,
|
|
38
|
+
LanguageSpan,
|
|
39
|
+
NormalizedText,
|
|
40
|
+
NormalizedToken,
|
|
41
|
+
Provenance,
|
|
42
|
+
Relationship,
|
|
43
|
+
ResolutionContractError,
|
|
44
|
+
ResolutionRecord,
|
|
45
|
+
SourceMessage,
|
|
46
|
+
SpeakerRef,
|
|
47
|
+
SubjectRef,
|
|
48
|
+
TemporalExpression,
|
|
49
|
+
TextEdit,
|
|
50
|
+
validate_record,
|
|
51
|
+
)
|
|
52
|
+
from .host import (
|
|
53
|
+
HostShadowObserver,
|
|
54
|
+
HostShadowReport,
|
|
55
|
+
ShadowSettings,
|
|
56
|
+
write_json_report,
|
|
57
|
+
)
|
|
58
|
+
from .identity import (
|
|
59
|
+
IdentityRegistry,
|
|
60
|
+
IdentityResult,
|
|
61
|
+
IdentitySession,
|
|
62
|
+
PersonRecord,
|
|
63
|
+
resolve_identity,
|
|
64
|
+
)
|
|
65
|
+
from .ingest import (
|
|
66
|
+
DEFAULT_POLICY,
|
|
67
|
+
IngestedChunk,
|
|
68
|
+
IngestedMessage,
|
|
69
|
+
IngestionPolicy,
|
|
70
|
+
MessageTooLongError,
|
|
71
|
+
OVERFLOW_POLICIES,
|
|
72
|
+
absorb_ingested,
|
|
73
|
+
ingest_conversation,
|
|
74
|
+
ingest_message,
|
|
75
|
+
)
|
|
76
|
+
from .interpret import Interpretation, interpret
|
|
77
|
+
from .language import detect_language
|
|
78
|
+
from .native import (
|
|
79
|
+
NativeConversion,
|
|
80
|
+
NativeConversionError,
|
|
81
|
+
NativeObservation,
|
|
82
|
+
RejectedFact,
|
|
83
|
+
native_identifier,
|
|
84
|
+
native_ingestion_id,
|
|
85
|
+
native_observations,
|
|
86
|
+
native_observations_many,
|
|
87
|
+
resolve_timestamp,
|
|
88
|
+
)
|
|
89
|
+
from .normalize import normalize_text
|
|
90
|
+
from .pipeline import ResolutionResult, Resolver, resolve_messages
|
|
91
|
+
from .relationships import (
|
|
92
|
+
FactIndex,
|
|
93
|
+
IndexedFact,
|
|
94
|
+
RelationshipRegistry,
|
|
95
|
+
RelationshipResult,
|
|
96
|
+
classify_relationships,
|
|
97
|
+
)
|
|
98
|
+
from .schema import SCHEMA, validate_with_schema
|
|
99
|
+
from .segments import MAX_MESSAGE_CHARS, MessageChunk, segment_message
|
|
100
|
+
from .shadow import ShadowReport, ShadowRunner
|
|
101
|
+
from .similarity import build_similarity
|
|
102
|
+
|
|
103
|
+
__all__ = [
|
|
104
|
+
"ACTIVE_WARNING",
|
|
105
|
+
"ATTRIBUTION_SCOPES",
|
|
106
|
+
"ATTRIBUTION_STATUSES",
|
|
107
|
+
"Attribution",
|
|
108
|
+
"BridgeDecision",
|
|
109
|
+
"DEFAULT_CONFIG",
|
|
110
|
+
"DEFAULT_POLICY",
|
|
111
|
+
"ENTITY_TYPES",
|
|
112
|
+
"Entity",
|
|
113
|
+
"Evidence",
|
|
114
|
+
"FactCandidate",
|
|
115
|
+
"FactIndex",
|
|
116
|
+
"HostShadowObserver",
|
|
117
|
+
"HostShadowReport",
|
|
118
|
+
"IdentityRegistry",
|
|
119
|
+
"IdentityResult",
|
|
120
|
+
"IdentitySession",
|
|
121
|
+
"IdentityTransition",
|
|
122
|
+
"IndexedFact",
|
|
123
|
+
"IngestedChunk",
|
|
124
|
+
"IngestedMessage",
|
|
125
|
+
"IngestionPolicy",
|
|
126
|
+
"Interpretation",
|
|
127
|
+
"LanguageInfo",
|
|
128
|
+
"LanguageSpan",
|
|
129
|
+
"MAX_MESSAGE_CHARS",
|
|
130
|
+
"MODES",
|
|
131
|
+
"MessageChunk",
|
|
132
|
+
"MessageTooLongError",
|
|
133
|
+
"NativeConversion",
|
|
134
|
+
"NativeConversionError",
|
|
135
|
+
"NativeObservation",
|
|
136
|
+
"NormalizedText",
|
|
137
|
+
"NormalizedToken",
|
|
138
|
+
"OVERFLOW_POLICIES",
|
|
139
|
+
"PersonRecord",
|
|
140
|
+
"Provenance",
|
|
141
|
+
"RELATIONSHIP_LABELS",
|
|
142
|
+
"RejectedFact",
|
|
143
|
+
"Relationship",
|
|
144
|
+
"RelationshipRegistry",
|
|
145
|
+
"RelationshipResult",
|
|
146
|
+
"ResolutionConfig",
|
|
147
|
+
"ResolutionContractError",
|
|
148
|
+
"ResolutionRecord",
|
|
149
|
+
"ResolutionResult",
|
|
150
|
+
"Resolver",
|
|
151
|
+
"SCHEMA",
|
|
152
|
+
"STAGE_NAMES",
|
|
153
|
+
"SUBJECT_KINDS",
|
|
154
|
+
"ShadowReport",
|
|
155
|
+
"ShadowRunner",
|
|
156
|
+
"ShadowSettings",
|
|
157
|
+
"SourceMessage",
|
|
158
|
+
"SpeakerRef",
|
|
159
|
+
"SubjectRef",
|
|
160
|
+
"TemporalExpression",
|
|
161
|
+
"TextEdit",
|
|
162
|
+
"absorb_ingested",
|
|
163
|
+
"absorb_record",
|
|
164
|
+
"build_similarity",
|
|
165
|
+
"candidates_for",
|
|
166
|
+
"classify_relationships",
|
|
167
|
+
"decide",
|
|
168
|
+
"detect_language",
|
|
169
|
+
"eligibility_counts",
|
|
170
|
+
"ingest_conversation",
|
|
171
|
+
"ingest_message",
|
|
172
|
+
"interpret",
|
|
173
|
+
"native_identifier",
|
|
174
|
+
"native_ingestion_id",
|
|
175
|
+
"native_observations",
|
|
176
|
+
"native_observations_many",
|
|
177
|
+
"normalize_text",
|
|
178
|
+
"resolve_identity",
|
|
179
|
+
"resolve_messages",
|
|
180
|
+
"resolve_timestamp",
|
|
181
|
+
"segment_message",
|
|
182
|
+
"subject_text",
|
|
183
|
+
"validate_record",
|
|
184
|
+
"validate_with_schema",
|
|
185
|
+
"write_json_report",
|
|
186
|
+
]
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
"""Explicit, opt-in bridge from resolution records to the MINEMOS engine.
|
|
2
|
+
|
|
3
|
+
The resolution layer never writes memory on its own. This module is the only
|
|
4
|
+
place that hands candidates to the engine, and it does so only when:
|
|
5
|
+
|
|
6
|
+
* the resolver is explicitly in ``active`` mode, **and**
|
|
7
|
+
* the caller calls :func:`absorb_record` / :func:`apply_records` directly.
|
|
8
|
+
|
|
9
|
+
Eligibility is deliberately narrow:
|
|
10
|
+
|
|
11
|
+
* the subject must be resolved (an unknown or ambiguous subject is never
|
|
12
|
+
invented into a candidate);
|
|
13
|
+
* the fact must be asserted with positive polarity (the engine has no way to
|
|
14
|
+
store a negated observation, so a negated candidate would become a false
|
|
15
|
+
positive assertion);
|
|
16
|
+
* the fact must not be classified ``unresolved`` against its own conversation
|
|
17
|
+
(an ambiguous conflict is left for a human or for the engine's own
|
|
18
|
+
contradiction logic, not silently asserted);
|
|
19
|
+
* a relationship classified ``duplicate`` is not sent again — re-absorbing an
|
|
20
|
+
identical fact would add no information.
|
|
21
|
+
|
|
22
|
+
The engine keeps every downstream decision: consolidation, contradiction,
|
|
23
|
+
supersession, temporal intervals, retention and eviction.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from dataclasses import dataclass
|
|
29
|
+
from typing import Dict, List, Iterable, Optional, Tuple
|
|
30
|
+
|
|
31
|
+
from .config import ResolutionConfig
|
|
32
|
+
from .contracts import FactCandidate, Relationship, ResolutionRecord, SubjectRef
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class BridgeDecision:
|
|
37
|
+
fact_id: str
|
|
38
|
+
accepted: bool
|
|
39
|
+
reason: str
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def subject_text(subject: SubjectRef, speaker: Optional[str]) -> Optional[str]:
|
|
43
|
+
"""Human-facing subject string, or None when it is not resolved."""
|
|
44
|
+
if subject.status != "resolved":
|
|
45
|
+
return None
|
|
46
|
+
if subject.kind == "speaker":
|
|
47
|
+
return subject.owner or speaker or "user"
|
|
48
|
+
if subject.kind == "derived":
|
|
49
|
+
if not subject.relation:
|
|
50
|
+
return None
|
|
51
|
+
return subject.label or f"user's {subject.relation}"
|
|
52
|
+
if subject.kind == "named":
|
|
53
|
+
return subject.label
|
|
54
|
+
return None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _relationship_for(record: ResolutionRecord,
|
|
58
|
+
fact_id: str) -> Optional[Relationship]:
|
|
59
|
+
for index, fact in enumerate(record.facts):
|
|
60
|
+
if fact.fact_id == fact_id and index < len(record.relationships):
|
|
61
|
+
return record.relationships[index]
|
|
62
|
+
return None
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def decide(record: ResolutionRecord, fact: FactCandidate,
|
|
66
|
+
config: Optional[ResolutionConfig] = None) -> BridgeDecision:
|
|
67
|
+
cfg = config or ResolutionConfig()
|
|
68
|
+
if cfg.mode != "active":
|
|
69
|
+
return BridgeDecision(fact.fact_id, False, "mode_is_not_active")
|
|
70
|
+
if fact.polarity != "positive":
|
|
71
|
+
return BridgeDecision(fact.fact_id, False, "non_asserted_polarity")
|
|
72
|
+
if fact.modality != "asserted":
|
|
73
|
+
return BridgeDecision(fact.fact_id, False, "non_asserted_modality")
|
|
74
|
+
if subject_text(fact.subject, record.source.speaker) is None:
|
|
75
|
+
return BridgeDecision(fact.fact_id, False, "subject_unresolved")
|
|
76
|
+
relationship = _relationship_for(record, fact.fact_id)
|
|
77
|
+
if relationship is not None and relationship.label in (
|
|
78
|
+
"duplicate", "unresolved"):
|
|
79
|
+
return BridgeDecision(
|
|
80
|
+
fact.fact_id, False, f"relationship_{relationship.label}")
|
|
81
|
+
return BridgeDecision(fact.fact_id, True, "eligible")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def candidates_for(record: ResolutionRecord,
|
|
85
|
+
config: Optional[ResolutionConfig] = None
|
|
86
|
+
) -> Tuple[List[object], List[BridgeDecision]]:
|
|
87
|
+
"""Builds engine ``Candidate`` objects for the eligible facts."""
|
|
88
|
+
from minemos_engine.structured_candidate import Candidate
|
|
89
|
+
|
|
90
|
+
cfg = config or ResolutionConfig()
|
|
91
|
+
candidates: List[object] = []
|
|
92
|
+
decisions: List[BridgeDecision] = []
|
|
93
|
+
timestamp = record.source.timestamp or 0.0
|
|
94
|
+
for fact in record.facts:
|
|
95
|
+
decision = decide(record, fact, cfg)
|
|
96
|
+
decisions.append(decision)
|
|
97
|
+
if not decision.accepted:
|
|
98
|
+
continue
|
|
99
|
+
subject = subject_text(fact.subject, record.source.speaker)
|
|
100
|
+
candidates.append(Candidate(
|
|
101
|
+
subject=subject,
|
|
102
|
+
predicate=fact.predicate,
|
|
103
|
+
object=fact.value,
|
|
104
|
+
confidence=round(fact.confidence, 4),
|
|
105
|
+
timestamp=timestamp,
|
|
106
|
+
))
|
|
107
|
+
return candidates, decisions
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def absorb_record(engine, record: ResolutionRecord,
|
|
111
|
+
config: Optional[ResolutionConfig] = None
|
|
112
|
+
) -> Dict[str, object]:
|
|
113
|
+
"""Absorbs the eligible candidates of one record into ``engine``.
|
|
114
|
+
|
|
115
|
+
``engine`` is a :class:`minemos_engine.BlackHoleMemory` instance. The
|
|
116
|
+
caller owns that object and its canonical state; this function performs no
|
|
117
|
+
other mutation.
|
|
118
|
+
"""
|
|
119
|
+
cfg = config or ResolutionConfig()
|
|
120
|
+
if cfg.mode != "active":
|
|
121
|
+
return {
|
|
122
|
+
"absorbed": 0,
|
|
123
|
+
"skipped": len(record.facts),
|
|
124
|
+
"reason": "mode_is_not_active",
|
|
125
|
+
"decisions": [],
|
|
126
|
+
}
|
|
127
|
+
candidates, decisions = candidates_for(record, cfg)
|
|
128
|
+
absorbed = 0
|
|
129
|
+
timestamp = record.source.timestamp
|
|
130
|
+
for candidate in candidates:
|
|
131
|
+
engine.absorb(candidate, timestamp=timestamp)
|
|
132
|
+
absorbed += 1
|
|
133
|
+
return {
|
|
134
|
+
"absorbed": absorbed,
|
|
135
|
+
"skipped": len(decisions) - absorbed,
|
|
136
|
+
"reason": "ok",
|
|
137
|
+
"decisions": [decision.__dict__ for decision in decisions],
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def eligibility_counts(record: ResolutionRecord,
|
|
142
|
+
config: Optional[ResolutionConfig] = None
|
|
143
|
+
) -> Dict[str, int]:
|
|
144
|
+
"""Counts bridge decisions without building candidates."""
|
|
145
|
+
cfg = config or ResolutionConfig()
|
|
146
|
+
counts: Dict[str, int] = {}
|
|
147
|
+
for fact in record.facts:
|
|
148
|
+
decision = decide(record, fact, cfg)
|
|
149
|
+
counts[decision.reason] = counts.get(decision.reason, 0) + 1
|
|
150
|
+
return counts
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
__all__ = [
|
|
154
|
+
"BridgeDecision",
|
|
155
|
+
"absorb_record",
|
|
156
|
+
"candidates_for",
|
|
157
|
+
"decide",
|
|
158
|
+
"eligibility_counts",
|
|
159
|
+
"subject_text",
|
|
160
|
+
]
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"""Configuration for the semantic resolution layer.
|
|
2
|
+
|
|
3
|
+
The layer is local-first. No provider is contacted unless the host passes
|
|
4
|
+
one explicitly, and the built-in providers are deterministic: a hash-based
|
|
5
|
+
lexical similarity provider (always available) and an optional wrapper around
|
|
6
|
+
the engine's existing local sentence encoder. There is no bundled network
|
|
7
|
+
client and no default endpoint.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from dataclasses import dataclass, replace
|
|
13
|
+
|
|
14
|
+
MODES = ("disabled", "shadow", "active")
|
|
15
|
+
|
|
16
|
+
ACTIVE_WARNING = (
|
|
17
|
+
"active mode feeds resolution candidates to the engine; the engine remains "
|
|
18
|
+
"the memory authority and keeps its own consolidation, contradiction, "
|
|
19
|
+
"temporal and retention decisions"
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class ResolutionConfig:
|
|
25
|
+
"""Immutable configuration for one resolver instance.
|
|
26
|
+
|
|
27
|
+
``mode`` is ``"shadow"`` by default: the layer processes conversations and
|
|
28
|
+
produces records, but nothing is written to canonical memory. ``"active"``
|
|
29
|
+
opt-in is only meaningful for callers that pass records to the engine
|
|
30
|
+
bridge; the resolver itself never mutates memory in either mode.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
mode: str = "shadow"
|
|
34
|
+
|
|
35
|
+
# Stage 1 — noise normalization
|
|
36
|
+
normalize_typos: bool = True
|
|
37
|
+
normalize_contractions: bool = True
|
|
38
|
+
normalize_informal: bool = True
|
|
39
|
+
normalize_whitespace: bool = True
|
|
40
|
+
max_typo_edits: int = 1
|
|
41
|
+
# Structural words (verbs and attribute names) may be recovered one edit
|
|
42
|
+
# away; values and names are never recovered this way.
|
|
43
|
+
max_structural_edits: int = 1
|
|
44
|
+
typo_min_length: int = 3
|
|
45
|
+
typo_confidence: float = 0.82
|
|
46
|
+
preserve_capitalized: bool = True
|
|
47
|
+
detect_language: bool = True
|
|
48
|
+
|
|
49
|
+
# Stage 2 — semantic interpretation
|
|
50
|
+
extract_facts: bool = True
|
|
51
|
+
max_facts_per_message: int = 12
|
|
52
|
+
extraction_confidence: float = 0.62
|
|
53
|
+
expand_place_aliases: bool = True
|
|
54
|
+
|
|
55
|
+
# Stage 3 — identity and provenance
|
|
56
|
+
resolve_pronouns: bool = True
|
|
57
|
+
pronoun_window: int = 6
|
|
58
|
+
conversation_scope_only: bool = True
|
|
59
|
+
link_repeated_variants: bool = True
|
|
60
|
+
repeated_variant_support: int = 2
|
|
61
|
+
name_variant_max_distance: int = 2
|
|
62
|
+
|
|
63
|
+
# Stage 4 — fact relationships
|
|
64
|
+
duplicate_similarity: float = 0.86
|
|
65
|
+
ambiguous_similarity: float = 0.62
|
|
66
|
+
semantic_provider: str = "hash" # "hash" | "local" | "none"
|
|
67
|
+
|
|
68
|
+
# Diagnostics
|
|
69
|
+
include_spans: bool = True
|
|
70
|
+
|
|
71
|
+
def __post_init__(self) -> None:
|
|
72
|
+
if self.mode not in MODES:
|
|
73
|
+
raise ValueError(
|
|
74
|
+
f"mode must be one of {MODES}, got {self.mode!r}")
|
|
75
|
+
if self.max_typo_edits < 0:
|
|
76
|
+
raise ValueError("max_typo_edits cannot be negative")
|
|
77
|
+
if self.max_structural_edits < 0:
|
|
78
|
+
raise ValueError("max_structural_edits cannot be negative")
|
|
79
|
+
if self.typo_min_length < 2:
|
|
80
|
+
raise ValueError("typo_min_length must be at least 2")
|
|
81
|
+
for name in ("typo_confidence", "extraction_confidence",
|
|
82
|
+
"duplicate_similarity", "ambiguous_similarity"):
|
|
83
|
+
value = getattr(self, name)
|
|
84
|
+
if not 0.0 <= float(value) <= 1.0:
|
|
85
|
+
raise ValueError(f"{name} must be within [0, 1]")
|
|
86
|
+
if self.ambiguous_similarity >= self.duplicate_similarity:
|
|
87
|
+
raise ValueError(
|
|
88
|
+
"ambiguous_similarity must be below duplicate_similarity")
|
|
89
|
+
if self.pronoun_window < 0:
|
|
90
|
+
raise ValueError("pronoun_window cannot be negative")
|
|
91
|
+
if self.semantic_provider not in ("hash", "local", "none"):
|
|
92
|
+
raise ValueError(
|
|
93
|
+
"semantic_provider must be 'hash', 'local' or 'none'")
|
|
94
|
+
|
|
95
|
+
@property
|
|
96
|
+
def shadow(self) -> bool:
|
|
97
|
+
return self.mode == "shadow"
|
|
98
|
+
|
|
99
|
+
@property
|
|
100
|
+
def active(self) -> bool:
|
|
101
|
+
return self.mode == "active"
|
|
102
|
+
|
|
103
|
+
@property
|
|
104
|
+
def enabled(self) -> bool:
|
|
105
|
+
return self.mode != "disabled"
|
|
106
|
+
|
|
107
|
+
def with_mode(self, mode: str) -> "ResolutionConfig":
|
|
108
|
+
return replace(self, mode=mode)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
DEFAULT_CONFIG = ResolutionConfig()
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
__all__ = ["ACTIVE_WARNING", "DEFAULT_CONFIG", "MODES", "ResolutionConfig"]
|