dil-banking 1.0.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.
dil/__init__.py ADDED
@@ -0,0 +1,58 @@
1
+ """
2
+ Domain Intelligence Layer (DIL) - Banking
3
+ A reusable intelligence infrastructure for AI applications in banking.
4
+ """
5
+
6
+ from dil.core.engine import DIL, Agent
7
+ from dil.core.loader import LoadedPack, PackLoader
8
+ from dil.core.models import (
9
+ ConceptItem,
10
+ ContextResult,
11
+ PackManifest,
12
+ ProcessItem,
13
+ RelationshipItem,
14
+ RoleDefinition,
15
+ RuleEvaluationResult,
16
+ RuleItem,
17
+ SourceItem,
18
+ TerminologyItem,
19
+ )
20
+ from dil.core.registry import DomainRegistry
21
+ from dil.llm.providers import (
22
+ create_gemini_callable,
23
+ create_generic_callable,
24
+ create_ollama_callable,
25
+ create_openai_callable,
26
+ )
27
+ from dil.roles.manager import RoleManager
28
+ from dil.rules.engine import RulesEngine
29
+ from dil.storage.engine import FTSStorageEngine
30
+ from dil.storage.parquet_exporter import ParquetPackExporter
31
+
32
+ __version__ = "1.0.0"
33
+
34
+ __all__ = [
35
+ "DIL",
36
+ "Agent",
37
+ "DomainRegistry",
38
+ "PackLoader",
39
+ "LoadedPack",
40
+ "RulesEngine",
41
+ "RoleManager",
42
+ "FTSStorageEngine",
43
+ "ParquetPackExporter",
44
+ "ContextResult",
45
+ "PackManifest",
46
+ "ConceptItem",
47
+ "TerminologyItem",
48
+ "RelationshipItem",
49
+ "ProcessItem",
50
+ "RuleItem",
51
+ "SourceItem",
52
+ "RoleDefinition",
53
+ "RuleEvaluationResult",
54
+ "create_openai_callable",
55
+ "create_gemini_callable",
56
+ "create_ollama_callable",
57
+ "create_generic_callable",
58
+ ]
dil/core/engine.py ADDED
@@ -0,0 +1,288 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Callable, Dict, List, Optional, Tuple
4
+
5
+ from dil.core.loader import LoadedPack
6
+ from dil.core.models import ContextResult, RoleDefinition, RuleEvaluationResult
7
+ from dil.core.registry import DomainRegistry
8
+ from dil.intelligence.context_builder import ContextBuilder
9
+ from dil.intelligence.extractor import ConversationalParameterExtractor
10
+ from dil.intelligence.matcher import IntelligenceMatcher
11
+ from dil.roles.manager import RoleManager
12
+ from dil.rules.engine import RulesEngine
13
+ from dil.storage.engine import FTSStorageEngine
14
+
15
+
16
+ class Agent:
17
+ """
18
+ Role-configured DIL Agent.
19
+ Combines domain intelligence, role boundaries, deterministic rules,
20
+ and optional customer data to prepare grounded prompts or orchestrate responses.
21
+ """
22
+
23
+ def __init__(
24
+ self,
25
+ dil: "DIL",
26
+ role: RoleDefinition,
27
+ developer_rules: Optional[List[str]] = None,
28
+ objective: Optional[str] = None,
29
+ ):
30
+ self.dil = dil
31
+ self.role = role
32
+ self.developer_rules = developer_rules or []
33
+ self.objective = objective or role.objective
34
+
35
+ def prepare(
36
+ self,
37
+ question: str,
38
+ customer_data: Optional[Dict[str, Any]] = None,
39
+ history: Optional[List[Dict[str, str]]] = None,
40
+ top_k: int = 5,
41
+ ) -> Tuple[ContextResult, List[Dict[str, str]]]:
42
+ """Prepares domain context and provider-neutral chat messages."""
43
+ return self.dil.build_messages(
44
+ query=question,
45
+ role=self.role,
46
+ customer_data=customer_data,
47
+ history=history,
48
+ developer_rules=self.developer_rules,
49
+ top_k=top_k,
50
+ )
51
+
52
+ def ask(
53
+ self,
54
+ question: str,
55
+ llm_callable: Callable[..., Any],
56
+ customer_data: Optional[Dict[str, Any]] = None,
57
+ history: Optional[List[Dict[str, str]]] = None,
58
+ top_k: int = 5,
59
+ **kwargs: Any,
60
+ ) -> Any:
61
+ """
62
+ Sends the prepared context and question to the provided LLM function.
63
+ The llm_callable must accept a 'messages' keyword argument.
64
+ """
65
+ result, messages = self.prepare(
66
+ question=question,
67
+ customer_data=customer_data,
68
+ history=history,
69
+ top_k=top_k,
70
+ )
71
+ return llm_callable(messages=messages, **kwargs)
72
+
73
+
74
+ class DIL:
75
+ """
76
+ Domain Intelligence Layer (DIL) Engine.
77
+ Coordinates domain packs, ontology retrieval, role management, and deterministic rules.
78
+ """
79
+
80
+ def __init__(
81
+ self,
82
+ domain: str = "banking",
83
+ jurisdiction: str = "global",
84
+ version: Optional[str] = None,
85
+ custom_packs_dir: Optional[str] = None,
86
+ ):
87
+ self.domain = domain.lower()
88
+ self.jurisdiction = jurisdiction.lower()
89
+ self.registry = DomainRegistry(custom_packs_dir=custom_packs_dir)
90
+ self.pack: LoadedPack = self.registry.get_pack(domain=self.domain, version=version)
91
+ self.storage = FTSStorageEngine()
92
+ self.storage.index_pack(self.pack)
93
+ self.matcher = IntelligenceMatcher(self.pack)
94
+ self.rules_engine = RulesEngine(self.pack.rules)
95
+ self.role_manager = RoleManager()
96
+
97
+ def get_context(
98
+ self,
99
+ query: str,
100
+ role: Optional[RoleDefinition | str] = None,
101
+ customer_data: Optional[Dict[str, Any]] = None,
102
+ developer_rules: Optional[List[str]] = None,
103
+ top_k: int = 5,
104
+ ) -> ContextResult:
105
+ """
106
+ Retrieves relevant domain concepts, extracts conversational parameters,
107
+ evaluates deterministic rules, and generates structured context.
108
+ """
109
+ # Resolve role
110
+ role_def: Optional[RoleDefinition] = None
111
+ if isinstance(role, str):
112
+ role_def = self.role_manager.get_role(role)
113
+ elif isinstance(role, RoleDefinition):
114
+ role_def = role
115
+
116
+ # 1. Match concepts and terminology
117
+ concepts, terms, scores = self.matcher.match(
118
+ query=query,
119
+ jurisdiction=self.jurisdiction,
120
+ max_concepts=top_k,
121
+ )
122
+
123
+ # 2. Extract conversational financial parameters from query
124
+ extracted_params = ConversationalParameterExtractor.extract(query)
125
+
126
+ # 3. Derive helper parameters from customer data + extracted parameters
127
+ eval_params: Dict[str, Any] = {}
128
+ if customer_data:
129
+ eval_params.update(customer_data)
130
+ eval_params.update(extracted_params)
131
+
132
+ # Automatic ratio computations (code does the math, not the LLM)
133
+ if "loan_amount" in eval_params and "property_value" in eval_params:
134
+ try:
135
+ pv = float(eval_params["property_value"])
136
+ if pv > 0:
137
+ eval_params["ltv_ratio"] = round(float(eval_params["loan_amount"]) / pv, 4)
138
+ except (ValueError, ZeroDivisionError):
139
+ pass
140
+
141
+ if "monthly_income" in eval_params and "existing_emi" in eval_params:
142
+ try:
143
+ income = float(eval_params["monthly_income"])
144
+ if income > 0:
145
+ eval_params["dti_ratio"] = round(float(eval_params["existing_emi"]) / income, 4)
146
+ except (ValueError, ZeroDivisionError):
147
+ pass
148
+
149
+ if "credit_score" in eval_params and "cibil_score" not in eval_params:
150
+ eval_params["cibil_score"] = eval_params["credit_score"]
151
+
152
+ # 4. Evaluate deterministic rules
153
+ evaluated_rules: List[RuleEvaluationResult] = []
154
+ if eval_params:
155
+ evaluated_rules = self.rules_engine.evaluate_all(
156
+ parameters=eval_params,
157
+ jurisdiction=self.jurisdiction,
158
+ )
159
+
160
+ # 5. Determine if domain is active
161
+ # Activated if role is explicitly assigned, concepts matched, terms matched, rules were evaluated, or financial parameters found
162
+ domain_active = bool(role_def or concepts or terms or evaluated_rules or extracted_params)
163
+
164
+ # 6. Assemble context text
165
+ effective_customer_data = eval_params if eval_params else None
166
+ context_text = ContextBuilder.build(
167
+ query=query,
168
+ domain=self.domain,
169
+ jurisdiction=self.jurisdiction,
170
+ role=role_def if domain_active else None,
171
+ concepts=concepts,
172
+ terms=terms,
173
+ evaluated_rules=evaluated_rules,
174
+ processes=self.pack.processes if domain_active else [],
175
+ customer_data=effective_customer_data,
176
+ developer_rules=developer_rules if domain_active else None,
177
+ )
178
+
179
+ return ContextResult(
180
+ query=query,
181
+ domain_active=domain_active,
182
+ extracted_parameters=extracted_params,
183
+ detected_concepts=[c.id for c in concepts],
184
+ selected_concepts=concepts,
185
+ detected_terms=terms,
186
+ evaluated_rules=evaluated_rules,
187
+ relevant_processes=self.pack.processes if domain_active else [],
188
+ context_text=context_text,
189
+ scores=scores,
190
+ )
191
+
192
+ def build_messages(
193
+ self,
194
+ query: str,
195
+ role: Optional[RoleDefinition | str] = None,
196
+ customer_data: Optional[Dict[str, Any]] = None,
197
+ history: Optional[List[Dict[str, str]]] = None,
198
+ developer_rules: Optional[List[str]] = None,
199
+ top_k: int = 5,
200
+ ) -> Tuple[ContextResult, List[Dict[str, str]]]:
201
+ """Constructs provider-agnostic system and user message payload with conversation history."""
202
+ result = self.get_context(
203
+ query=query,
204
+ role=role,
205
+ customer_data=customer_data,
206
+ developer_rules=developer_rules,
207
+ top_k=top_k,
208
+ )
209
+
210
+ if result.domain_active:
211
+ if isinstance(role, str):
212
+ role_instructions = self.role_manager.get_role(role).system_instructions
213
+ elif isinstance(role, RoleDefinition):
214
+ role_instructions = role.system_instructions
215
+ else:
216
+ role_instructions = (
217
+ "You are an AI assistant specialized in banking and financial services. "
218
+ "Provide factual, clear, and structured answers grounded strictly in banking "
219
+ "domain knowledge and evaluated rules. Distinguish general banking principles "
220
+ "from bank-specific policies, and enforce credit cautions."
221
+ )
222
+ user_content = (result.context_text + f"\n\nUSER QUESTION: {query}") if result.context_text else query
223
+ else:
224
+ role_instructions = (
225
+ "You are a helpful, knowledgeable, and polite AI assistant. "
226
+ "Respond naturally, accurately, and concisely to the user's questions."
227
+ )
228
+ user_content = query
229
+
230
+ messages: List[Dict[str, str]] = [
231
+ {
232
+ "role": "system",
233
+ "content": role_instructions,
234
+ }
235
+ ]
236
+
237
+ # Multi-turn history support
238
+ if history:
239
+ for h in history[-8:]:
240
+ if h.get("role") in ("user", "assistant") and h.get("content"):
241
+ messages.append({"role": h["role"], "content": h["content"]})
242
+
243
+ messages.append({
244
+ "role": "user",
245
+ "content": user_content,
246
+ })
247
+
248
+ return result, messages
249
+
250
+ def create_agent(
251
+ self,
252
+ role: str | RoleDefinition,
253
+ developer_rules: Optional[List[str]] = None,
254
+ objective: Optional[str] = None,
255
+ ) -> Agent:
256
+ """Configures a reusable DIL Agent bound to a specific role."""
257
+ if isinstance(role, str):
258
+ role_def = self.role_manager.get_role(role)
259
+ else:
260
+ role_def = role
261
+
262
+ return Agent(
263
+ dil=self,
264
+ role=role_def,
265
+ developer_rules=developer_rules,
266
+ objective=objective,
267
+ )
268
+
269
+ def answer(
270
+ self,
271
+ query: str,
272
+ llm_callable: Callable[..., Any],
273
+ role: Optional[str | RoleDefinition] = None,
274
+ customer_data: Optional[Dict[str, Any]] = None,
275
+ history: Optional[List[Dict[str, str]]] = None,
276
+ top_k: int = 5,
277
+ **kwargs: Any,
278
+ ) -> Any:
279
+ """Directly evaluates context and passes to llm_callable."""
280
+ result, messages = self.build_messages(
281
+ query=query,
282
+ role=role,
283
+ customer_data=customer_data,
284
+ history=history,
285
+ top_k=top_k,
286
+ )
287
+ return llm_callable(messages=messages, **kwargs)
288
+
dil/core/loader.py ADDED
@@ -0,0 +1,150 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from pathlib import Path
5
+ from typing import Any, Dict, List, Optional
6
+
7
+ from dil.core.models import (
8
+ ConceptItem,
9
+ PackManifest,
10
+ ProcessItem,
11
+ ProcessStep,
12
+ RelationshipItem,
13
+ RuleItem,
14
+ SourceItem,
15
+ TerminologyItem,
16
+ )
17
+
18
+
19
+ class PackLoader:
20
+ """Loads and validates structured DIL Knowledge Packs from disk."""
21
+
22
+ @staticmethod
23
+ def load_pack(pack_dir: Path | str) -> "LoadedPack":
24
+ pack_path = Path(pack_dir)
25
+ manifest_file = pack_path / "manifest.json"
26
+ if not manifest_file.exists():
27
+ raise FileNotFoundError(f"Missing manifest.json in pack directory: {pack_path}")
28
+
29
+ with open(manifest_file, "r", encoding="utf-8") as f:
30
+ m_data = json.load(f)
31
+
32
+ manifest = PackManifest(
33
+ pack_id=m_data["pack_id"],
34
+ name=m_data["name"],
35
+ version=m_data["version"],
36
+ domain=m_data["domain"],
37
+ publisher=m_data["publisher"],
38
+ description=m_data["description"],
39
+ jurisdictions=m_data.get("jurisdictions", ["global"]),
40
+ compatibility=m_data.get("compatibility", {}),
41
+ assets=m_data.get("assets", {}),
42
+ release=m_data.get("release", {}),
43
+ )
44
+
45
+ # 1. Terminology
46
+ terms: List[TerminologyItem] = []
47
+ term_rel = manifest.assets.get("terminology")
48
+ if term_rel:
49
+ term_file = pack_path / term_rel
50
+ if term_file.exists():
51
+ with open(term_file, "r", encoding="utf-8") as f:
52
+ for item in json.load(f):
53
+ terms.append(TerminologyItem(**item))
54
+
55
+ # 2. Concepts
56
+ concepts: List[ConceptItem] = []
57
+ conc_rel = manifest.assets.get("concepts")
58
+ if conc_rel:
59
+ conc_file = pack_path / conc_rel
60
+ if conc_file.exists():
61
+ with open(conc_file, "r", encoding="utf-8") as f:
62
+ for item in json.load(f):
63
+ concepts.append(ConceptItem(**item))
64
+
65
+ # 3. Relationships
66
+ relationships: List[RelationshipItem] = []
67
+ rel_rel = manifest.assets.get("relationships")
68
+ if rel_rel:
69
+ rel_file = pack_path / rel_rel
70
+ if rel_file.exists():
71
+ with open(rel_file, "r", encoding="utf-8") as f:
72
+ for item in json.load(f):
73
+ relationships.append(RelationshipItem(**item))
74
+
75
+ # 4. Processes
76
+ processes: List[ProcessItem] = []
77
+ proc_rel = manifest.assets.get("processes")
78
+ if proc_rel:
79
+ proc_file = pack_path / proc_rel
80
+ if proc_file.exists():
81
+ with open(proc_file, "r", encoding="utf-8") as f:
82
+ for item in json.load(f):
83
+ steps = [ProcessStep(**s) for s in item.get("steps", [])]
84
+ proc_copy = dict(item)
85
+ proc_copy["steps"] = steps
86
+ processes.append(ProcessItem(**proc_copy))
87
+
88
+ # 5. Rules
89
+ rules: List[RuleItem] = []
90
+ rules_asset = manifest.assets.get("rules", {})
91
+ if isinstance(rules_asset, dict):
92
+ for jur_key, rel_path in rules_asset.items():
93
+ rule_file = pack_path / rel_path
94
+ if rule_file.exists():
95
+ with open(rule_file, "r", encoding="utf-8") as f:
96
+ for item in json.load(f):
97
+ rules.append(RuleItem(**item))
98
+ elif isinstance(rules_asset, str):
99
+ rules_dir = pack_path / rules_asset
100
+ if rules_dir.is_dir():
101
+ for rule_file in rules_dir.glob("*.json"):
102
+ with open(rule_file, "r", encoding="utf-8") as f:
103
+ for item in json.load(f):
104
+ rules.append(RuleItem(**item))
105
+
106
+ # 6. Sources
107
+ sources: List[SourceItem] = []
108
+ src_rel = manifest.assets.get("sources")
109
+ if src_rel:
110
+ src_file = pack_path / src_rel
111
+ if src_file.exists():
112
+ with open(src_file, "r", encoding="utf-8") as f:
113
+ for item in json.load(f):
114
+ sources.append(SourceItem(**item))
115
+
116
+ return LoadedPack(
117
+ manifest=manifest,
118
+ terminology=terms,
119
+ concepts=concepts,
120
+ relationships=relationships,
121
+ processes=processes,
122
+ rules=rules,
123
+ sources=sources,
124
+ )
125
+
126
+
127
+ class LoadedPack:
128
+ def __init__(
129
+ self,
130
+ manifest: PackManifest,
131
+ terminology: List[TerminologyItem],
132
+ concepts: List[ConceptItem],
133
+ relationships: List[RelationshipItem],
134
+ processes: List[ProcessItem],
135
+ rules: List[RuleItem],
136
+ sources: List[SourceItem],
137
+ ):
138
+ self.manifest = manifest
139
+ self.terminology = terminology
140
+ self.concepts = concepts
141
+ self.relationships = relationships
142
+ self.processes = processes
143
+ self.rules = rules
144
+ self.sources = sources
145
+
146
+ self.concepts_by_id: Dict[str, ConceptItem] = {c.id: c for c in concepts}
147
+ self.terms_by_name: Dict[str, TerminologyItem] = {t.term.lower(): t for t in terminology}
148
+ self.rules_by_id: Dict[str, RuleItem] = {r.id: r for r in rules}
149
+ self.sources_by_id: Dict[str, SourceItem] = {s.source_id: s for s in sources}
150
+
dil/core/models.py ADDED
@@ -0,0 +1,146 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Any, Dict, List, Optional
5
+
6
+
7
+ @dataclass
8
+ class PackManifest:
9
+ pack_id: str
10
+ name: str
11
+ version: str
12
+ domain: str
13
+ publisher: str
14
+ description: str
15
+ jurisdictions: List[str]
16
+ compatibility: Dict[str, str]
17
+ assets: Dict[str, Any]
18
+ release: Dict[str, str]
19
+
20
+
21
+ @dataclass
22
+ class TerminologyItem:
23
+ term: str
24
+ expansion: str
25
+ category: str
26
+ definition: str
27
+ synonyms: List[str] = field(default_factory=list)
28
+
29
+
30
+ @dataclass
31
+ class ConceptItem:
32
+ id: str
33
+ name: str
34
+ category: str
35
+ definition: str
36
+ key_points: List[str] = field(default_factory=list)
37
+ aliases: List[str] = field(default_factory=list)
38
+ related: List[str] = field(default_factory=list)
39
+ caveat: Optional[str] = None
40
+ jurisdiction: str = "global"
41
+
42
+
43
+ @dataclass
44
+ class RelationshipItem:
45
+ source: str
46
+ relation: str
47
+ target: str
48
+ description: str
49
+
50
+
51
+ @dataclass
52
+ class ProcessStep:
53
+ step_number: int
54
+ name: str
55
+ description: str
56
+
57
+
58
+ @dataclass
59
+ class ProcessItem:
60
+ id: str
61
+ name: str
62
+ category: str
63
+ description: str
64
+ steps: List[ProcessStep] = field(default_factory=list)
65
+
66
+
67
+ @dataclass
68
+ class RuleItem:
69
+ id: str
70
+ title: str
71
+ category: str
72
+ jurisdiction: str
73
+ parameter: str
74
+ operator: str
75
+ threshold: Any
76
+ on_fail: str
77
+ description: str
78
+ source_id: str
79
+ unit: Optional[str] = None
80
+ applies_when: Optional[str] = None
81
+
82
+
83
+ @dataclass
84
+ class SourceItem:
85
+ source_id: str
86
+ name: str
87
+ publisher: str
88
+ jurisdiction: str
89
+ document_ref: str
90
+ last_reviewed_date: str
91
+ status: str = "active"
92
+
93
+
94
+ @dataclass
95
+ class RoleDefinition:
96
+ role_id: str
97
+ name: str
98
+ description: str
99
+ objective: str
100
+ tone: str
101
+ system_instructions: str
102
+ rules: List[str] = field(default_factory=list)
103
+ disclaimers: List[str] = field(default_factory=list)
104
+
105
+
106
+ @dataclass
107
+ class RuleEvaluationResult:
108
+ rule_id: str
109
+ rule_title: str
110
+ passed: bool
111
+ status: str # "PASS", "FAIL", "REFER", "NOT_APPLICABLE"
112
+ parameter: str
113
+ actual_value: Any
114
+ threshold: Any
115
+ operator: str
116
+ message: str
117
+ source_id: str
118
+
119
+
120
+ @dataclass
121
+ class ContextResult:
122
+ query: str
123
+ detected_concepts: List[str]
124
+ selected_concepts: List[ConceptItem]
125
+ detected_terms: List[TerminologyItem]
126
+ evaluated_rules: List[RuleEvaluationResult]
127
+ relevant_processes: List[ProcessItem]
128
+ context_text: str
129
+ scores: Dict[str, float]
130
+ domain_active: bool = False
131
+ extracted_parameters: Dict[str, Any] = field(default_factory=dict)
132
+
133
+ def to_dict(self) -> Dict[str, Any]:
134
+ return {
135
+ "query": self.query,
136
+ "domain_active": self.domain_active,
137
+ "detected_concepts": self.detected_concepts,
138
+ "extracted_parameters": self.extracted_parameters,
139
+ "selected_concepts": [c.__dict__ for c in self.selected_concepts],
140
+ "detected_terms": [t.__dict__ for t in self.detected_terms],
141
+ "evaluated_rules": [r.__dict__ for r in self.evaluated_rules],
142
+ "relevant_processes": [p.__dict__ for p in self.relevant_processes],
143
+ "context_text": self.context_text,
144
+ "scores": self.scores,
145
+ }
146
+