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.
Files changed (55) hide show
  1. minemos/__init__.py +72 -0
  2. minemos/resolution/__init__.py +186 -0
  3. minemos/resolution/bridge.py +160 -0
  4. minemos/resolution/config.py +114 -0
  5. minemos/resolution/contracts.py +843 -0
  6. minemos/resolution/host.py +474 -0
  7. minemos/resolution/identity.py +840 -0
  8. minemos/resolution/ingest.py +240 -0
  9. minemos/resolution/interpret.py +1758 -0
  10. minemos/resolution/language.py +295 -0
  11. minemos/resolution/lexicon.py +634 -0
  12. minemos/resolution/native.py +367 -0
  13. minemos/resolution/normalize.py +514 -0
  14. minemos/resolution/pipeline.py +312 -0
  15. minemos/resolution/relationships.py +380 -0
  16. minemos/resolution/schema.json +257 -0
  17. minemos/resolution/schema.py +142 -0
  18. minemos/resolution/segments.py +119 -0
  19. minemos/resolution/shadow.py +160 -0
  20. minemos/resolution/similarity.py +221 -0
  21. minemos/semantic.py +388 -0
  22. minemos-0.1.0.dist-info/METADATA +472 -0
  23. minemos-0.1.0.dist-info/RECORD +55 -0
  24. minemos-0.1.0.dist-info/WHEEL +5 -0
  25. minemos-0.1.0.dist-info/licenses/LICENSE +202 -0
  26. minemos-0.1.0.dist-info/licenses/NOTICE +20 -0
  27. minemos-0.1.0.dist-info/top_level.txt +2 -0
  28. minemos_engine/__init__.py +29 -0
  29. minemos_engine/answer.py +60 -0
  30. minemos_engine/black_hole_memory.py +5160 -0
  31. minemos_engine/checkpoint.py +1026 -0
  32. minemos_engine/eligibility.py +403 -0
  33. minemos_engine/encoders.py +146 -0
  34. minemos_engine/evidence.py +895 -0
  35. minemos_engine/intelligence/__init__.py +0 -0
  36. minemos_engine/intelligence/addressing.py +524 -0
  37. minemos_engine/intelligence/bm25.py +677 -0
  38. minemos_engine/intelligence/consolidation.py +90 -0
  39. minemos_engine/intelligence/dense.py +435 -0
  40. minemos_engine/intelligence/nli.py +330 -0
  41. minemos_engine/intelligence/retention.py +169 -0
  42. minemos_engine/intelligence/utility.py +520 -0
  43. minemos_engine/intelligence/verification.py +171 -0
  44. minemos_engine/intelligence/verification_terms.py +393 -0
  45. minemos_engine/memory_state.py +255 -0
  46. minemos_engine/memory_update.py +127 -0
  47. minemos_engine/recall.py +54 -0
  48. minemos_engine/retrieval/__init__.py +66 -0
  49. minemos_engine/retrieval/adapter.py +270 -0
  50. minemos_engine/retrieval/config.py +125 -0
  51. minemos_engine/retrieval/incremental.py +471 -0
  52. minemos_engine/retrieval/qdrant.py +973 -0
  53. minemos_engine/retrieval/qdrant_config.py +197 -0
  54. minemos_engine/retrieval/snapshot.py +841 -0
  55. 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"]