covalve 0.1.0__py3-none-any.whl

covalve/__init__.py

@@ -0,0 +1,35 @@
+# entry point
+from covalve.runtime.pipeline import pipeline, base_schema
+
+# config & context
+from covalve.runtime.models.context import (
+    PipelineConfig,
+    PipelineContext,
+    ArgsCtx,
+    ReturnSchema,
+    SchemaCollections,
+)
+
+# infrastructure contracts
+from covalve.infrastructure.contract import InfrastructureRegistry
+from covalve.infrastructure.base.llm import LLMBase
+from covalve.infrastructure.base.memory import MemoryStoreBase
+from covalve.infrastructure.base.cache import CacheBase
+from covalve.infrastructure.base.tools import ToolClientBase
+from covalve.infrastructure.base.log import LogBase
+from covalve.infrastructure.base.guardrails import GuardrailBase
+
+# hook system
+from covalve.runtime.hook import hooks
+from covalve.runtime.hook.registry import HookOn
+from covalve.runtime.hook.context import ReadOnlyContext
+
+# io models
+from covalve.runtime.models.io import (
+    OutputSchema,
+    OutputStatus,
+    MainLLMResponse,
+    GenerateCondition,
+)
+from covalve.runtime.models.logs import StateLog
+from covalve.runtime.models.metadata import RuntimeMetadata, QueryIntent

covalve/infrastructure/base/cache.py

@@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class CacheBase(ABC):
+    @abstractmethod
+    async def get(self, key:str) -> str | None: ...
+
+    @abstractmethod
+    async def set(self, key: str, value: Any) -> None: ...
+    
+    @abstractmethod
+    async def delete(self, key: str) -> None: ...

covalve/infrastructure/base/guardrails.py

@@ -0,0 +1,6 @@
+from abc import ABC, abstractmethod
+from covalve.runtime.models.infra import BackgroundUnit, GuardRailResponse
+
+class GuardrailBase(ABC):
+    @abstractmethod
+    async def validate(self, query:str, background: BackgroundUnit) -> GuardRailResponse:...

covalve/infrastructure/base/llm.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+from covalve.runtime.models.io import MainLLMResponse,GenerateCondition 
+from covalve.runtime.models.context import RuntimeMetadata
+
+class LLMBase(ABC):
+    
+    @abstractmethod
+    async def analyze(self, context_payload: str) -> RuntimeMetadata: ...
+    
+    @abstractmethod
+    async def generate(self, context_payload: str, condition: GenerateCondition) -> MainLLMResponse: ...

covalve/infrastructure/base/log.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+from covalve.runtime.models.logs import StateLog
+
+class LogBase(ABC):
+    @abstractmethod
+    async def state_log(self, ctx: StateLog):
+        raise NotImplementedError("Log Client is not implemented yet")

covalve/infrastructure/base/memory.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+from covalve.runtime.models.io import DataContent 
+from covalve.runtime.models.infra import BackgroundUnit
+
+class MemoryStoreBase(ABC):
+    @abstractmethod
+    async def save_conv(self, content:DataContent):...
+
+    @abstractmethod
+    async def retrieve_conv(self, session_id:str) -> BackgroundUnit | None:...

covalve/infrastructure/base/tools.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+from covalve.runtime.models.context import RuntimeMetadata 
+from covalve.runtime.models.infra import MCPResponse
+
+class ToolClientBase(ABC):
+    @abstractmethod
+    async def retrieve(self, tool_name: str, metadata:RuntimeMetadata) -> MCPResponse: ...

covalve/infrastructure/contract.py

@@ -0,0 +1,20 @@
+
+from typing import Optional
+from dataclasses import dataclass
+from pydantic import BaseModel
+from covalve.infrastructure.base.memory import MemoryStoreBase
+from covalve.infrastructure.base.llm import LLMBase
+from covalve.infrastructure.base.log import LogBase
+from covalve.infrastructure.base.tools import ToolClientBase
+from covalve.infrastructure.base.cache import CacheBase
+from covalve.infrastructure.base.guardrails import GuardrailBase
+
+
+@dataclass
+class InfrastructureRegistry:
+    llm: Optional[LLMBase] = None
+    memory: Optional[MemoryStoreBase] = None
+    cache: Optional[CacheBase] = None
+    tools: Optional[ToolClientBase] = None
+    log: Optional[LogBase] = None
+    guardrail: Optional[GuardrailBase] = None

covalve/runtime/engine.py

@@ -0,0 +1,98 @@
+import hashlib
+import time
+import asyncio
+from datetime import datetime
+from covalve.runtime.models.context import PipelineContext, ArgsCtx, ReturnSchema, STOP, SchemaCollections
+from covalve.infrastructure.contract import InfrastructureRegistry
+from covalve.runtime.models.logs import StateLog
+from covalve.runtime.hook.executor import hook_executor
+from covalve.runtime.hook.registry import HookOn
+
+
+def _init_context(query, session_id) -> tuple[str, str, PipelineContext]:
+        new_session_id = session_id
+        now = datetime.now()
+        traceId = hashlib.sha256(f"traceId-{query}-{now}".encode('utf-8')).hexdigest()
+        if new_session_id is None:
+            new_session_id  = hashlib.sha256(f"{query}-{now}".encode('utf-8')).hexdigest()
+
+        new_contex = PipelineContext(is_error=False,query=query,session_id=new_session_id ,current_time=now,traceId=traceId)
+        return (traceId, new_session_id, new_contex)
+        
+
+async def _execute_state(states:dict, handlers, args_ctx:ArgsCtx) -> tuple[str, str, PipelineContext, str]:
+    error = ""
+    try:
+        result:ReturnSchema = await handlers(args_ctx)
+        running_context: PipelineContext = result.context
+        if result.event not in states[args_ctx.state]["transitions"] and not result.event == STOP.HANDLER_ERROR:
+            event_emmited = result.event
+            current_state = STOP.INVALID_EVENT
+        else:
+            event_emmited = result.event
+            current_state = states[args_ctx.state]["transitions"][event_emmited]["to"]
+    except Exception as e:
+        event_emmited = STOP.HANDLER_ERROR 
+        running_context = args_ctx.context
+        current_state = STOP.HANDLER_ERROR 
+        error = str(e)
+
+    return (event_emmited, current_state, running_context, error)
+
+        
+def _fire_state_log(deps:InfrastructureRegistry, log_data: StateLog) -> None:
+    asyncio.create_task(deps.log.state_log(log_data))
+
+
+
+def create_engine(schemaCols:SchemaCollections, handlers:dict, hooks:dict, deps:InfrastructureRegistry):
+    core_schema = schemaCols.core_schema
+
+    async def engine(query, session_id=None):
+        stop_state = [core_schema["FINAL"], STOP.INVALID_EVENT, STOP.HANDLER_ERROR, STOP.INTERCEPTOR_ERROR]     
+        traceId, new_session_id, new_context = _init_context(query, session_id)
+        running_context = new_context
+
+        current_state = core_schema["INITIAL"]   
+        active_state = core_schema["INITIAL"]
+        while current_state not in stop_state:
+            error_string = ""
+            args_ctx = ArgsCtx(state=current_state, context=running_context, schema=schemaCols)
+            handler = handlers[current_state]
+
+            start = time.perf_counter()
+
+            hook_result = await hook_executor(HookOn.ENTER,core_schema["states"],current_state,hooks,running_context)
+            if hook_result.intercepted:
+                current_state = hook_result.to
+                error_string = hook_result.error
+                event_emmited = hook_result.event
+            else:
+                event_emmited, current_state, running_context, error_string = await _execute_state(core_schema["states"], handler, args_ctx)
+
+                hook_result = await hook_executor(HookOn.EXIT,core_schema["states"],active_state,hooks,running_context)
+                if hook_result.intercepted:
+                    current_state = hook_result.to
+                    error_string = hook_result.error
+                    event_emmited = hook_result.event
+
+
+            log_data = StateLog(
+                session_id=new_session_id,
+                traceId=traceId,
+                current_state=active_state,
+                event= event_emmited,
+                error= error_string,
+                next_state=current_state,
+                time_executed=datetime.now(),
+                duration_ms = (time.perf_counter() - start) * 1000
+            )
+
+            _fire_state_log(deps, log_data)
+
+            active_state = current_state
+        return running_context
+
+    return engine
+    
+    

covalve/runtime/executor/analyze_query.py

@@ -0,0 +1,43 @@
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema, RuntimeMetadata
+from covalve.infrastructure.contract import InfrastructureRegistry
+from pydantic import ValidationError
+import json
+
+def factory_analyzer(deps: InfrastructureRegistry):
+    async def handle_analyze(ctx: ArgsCtx) -> ReturnSchema: 
+        copy_context = ctx.context.model_copy(deep=True)
+        prev_summarize = copy_context.background.summarize if copy_context.background else ""
+        prev_conv = [conv.model_dump(exclude={'data'}) for conv in copy_context.background.conversation] if ctx.context.background else []
+        context_payload = f"""
+
+            ## Summarize previous conversation
+            {prev_summarize}
+
+            ## Previous Conversation
+            {prev_conv}
+
+            ## Current Query
+            {copy_context.query}
+
+            ## Current Date
+            {copy_context.current_time.strftime('%Y-%m-%d')}
+        """
+
+        try:
+            metadata: RuntimeMetadata = await deps.llm.analyze(context_payload)
+            copy_context.metadata = metadata
+        except (ValidationError, json.JSONDecodeError) as e:
+            copy_context.error = {"type": "PARSE_ERROR", "detail": str(e)}
+            copy_context.last_error_emitted = ctx.state
+            return ReturnSchema(event='INTERNAL_ERROR', context=copy_context)
+
+        confidences = [unit.confidence for unit in metadata.content]
+        any_low = any(c < 0.5 for c in confidences)
+        mean_low = sum(confidences) / len(confidences) < 0.75
+        if any_low or mean_low:
+            return ReturnSchema(event='LOW_CONFIDENCE', context=copy_context)
+
+        return ReturnSchema(event= 'NEXT', context=copy_context)
+
+    return handle_analyze
+

covalve/runtime/executor/error.py

@@ -0,0 +1,14 @@
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema, OutputSchema 
+from covalve.runtime.models.io import OutputStatus 
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+def factory_internal_error(deps:InfrastructureRegistry):
+    async def handle_internal_server_error(ctx: ArgsCtx) -> ReturnSchema:
+        copy_context = ctx.context.model_copy(deep=True)
+        copy_context.response = OutputSchema(
+             text="Something went wrong. Please try again later.",
+            status=OutputStatus.ERROR,
+            traceId=copy_context.traceId
+        )
+        return ReturnSchema(event="NEXT", context=copy_context)
+    return handle_internal_server_error

covalve/runtime/executor/error_counter.py

@@ -0,0 +1,18 @@
+from covalve.runtime.models.context import  ArgsCtx, ReturnSchema 
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+def factory_error_counter(deps:InfrastructureRegistry):
+    async def handle_error_counter(ctx: ArgsCtx) -> ReturnSchema:
+        copy_context = ctx.context.model_copy(deep=True)
+        session_id = copy_context.session_id
+        emitter = copy_context.last_error_emitted
+        next_event = 'RETRY_TOOLS' if emitter == 'EXECUTE_TOOLS' else 'RETRY_ANALYZE'
+        key = f'{session_id}:{emitter}'
+        counter = int(await deps.cache.get(key) or 0)
+        counter += 1
+        await deps.cache.set(key, counter)
+        if counter >= 3:
+            next_event = 'RETRY_TIMES_OUT'
+        return ReturnSchema(event=next_event, context=copy_context)
+    return handle_error_counter
+

covalve/runtime/executor/fallback.py

@@ -0,0 +1,20 @@
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema 
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+
+def factory_fallback(deps:InfrastructureRegistry):
+    async def handle_fallback(ctx: ArgsCtx) -> ReturnSchema: 
+        copy_context = ctx.context.model_copy(deep=True)
+        content = copy_context.metadata.content if copy_context.metadata else [] 
+        copy_context.is_clarification = True
+        confidences = [unit.confidence for unit in content]
+
+        threshold = 0.5 if any(c < 0.5 for c in confidences) else 0.75
+
+        copy_context.fallback_content = [
+            item for item in content
+            if item.confidence < threshold
+        ]
+
+        return ReturnSchema(event="NEXT", context=copy_context)
+    return handle_fallback

covalve/runtime/executor/guardrail.py

@@ -0,0 +1,13 @@
+from covalve.infrastructure.contract import InfrastructureRegistry
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema
+
+def factory_guardrails(deps: InfrastructureRegistry):
+    async def handle_guardrails(ctx: ArgsCtx) -> ReturnSchema:
+        copy_context = ctx.context.model_copy(deep=True)
+        result = await deps.guardrail.validate(copy_context.query,copy_context.background)
+        if result.is_rejected:
+            copy_context.guardrail_rejection = result.reason
+            copy_context.is_clarification = True
+            return ReturnSchema(event='OUT_OF_SCOPE', context=copy_context)       
+        return ReturnSchema(event='NEXT', context=copy_context)
+    return handle_guardrails

covalve/runtime/executor/main_llm.py

@@ -0,0 +1,72 @@
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema, OutputSchema 
+from covalve.runtime.models.io import OutputStatus, MainLLMResponse, GenerateCondition
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+def factory_main_llm(deps: InfrastructureRegistry):
+    async def handle_main_llm(ctx: ArgsCtx) -> ReturnSchema:
+        copy_context = ctx.context.model_copy(deep=True)
+        tools_context = ""
+        if copy_context.tools_data:
+            for _, data in copy_context.tools_data.items():
+                intent_context = next(
+                    (unit.composition_context for unit in copy_context.metadata.content 
+                     if unit.intent in ['operate', 'lookup', 'validate', 'compare']),
+                    copy_context.query
+                )
+                tools_context += f"\n### Data for: '{intent_context}'\n{data}\n"
+        is_rejected = True if copy_context.guardrail_rejection else False
+        generate_condition = GenerateCondition(
+            is_clarification=copy_context.is_clarification, 
+            is_rejected=is_rejected)
+        context_payload = f"""
+
+            ## Data Hasil Query
+            {tools_context}
+
+            ## Previous Conversation
+            {copy_context.background}
+
+            ## Intent Analysis
+            {[unit.model_dump() for unit in copy_context.metadata.content] if copy_context.metadata else []}
+
+            ## Question
+            {copy_context.query}
+
+            ## Current Date
+            {copy_context.current_time.strftime('%Y-%m-%d')}
+        """ 
+
+        if copy_context.is_clarification:
+            clarification_section = f"## Clarification Context\n{copy_context.fallback_content}" if copy_context.fallback_content else ""
+            guardrail_section = f"## Out Of Context Reason\n{copy_context.guardrail_rejection}" if copy_context.guardrail_rejection else ""
+            context_payload = f"""
+
+            ## Previous Conversation
+            {copy_context.background}
+
+            {clarification_section}
+
+            {guardrail_section}
+            
+            ## Question
+            {copy_context.query}
+
+            ## Current Date
+            {copy_context.current_time.strftime('%Y-%m-%d')}
+
+            """
+
+        result_from_llm: MainLLMResponse = await deps.llm.generate(context_payload, generate_condition)
+        copy_context.summarize = result_from_llm.summarize
+
+        result = OutputSchema(
+            text=result_from_llm.text,
+            attachment= None,
+            status=OutputStatus.CLARIFICATION if copy_context.is_clarification else OutputStatus.SUCCESS,
+            traceId=copy_context.traceId
+        )
+
+        copy_context.response = result
+        return ReturnSchema(event="NEXT", context=copy_context)
+    return handle_main_llm
+

covalve/runtime/executor/retrieve_conv.py

@@ -0,0 +1,15 @@
+from covalve.runtime.models.context import ArgsCtx, ReturnSchema, BackgroundUnit
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+def factory_retrieve_memmory(deps:InfrastructureRegistry):
+    async def handle_retrieve_previous_conversation(ctx: ArgsCtx) -> ReturnSchema: 
+        copy_context = ctx.context.model_copy(deep=True)
+        session_id = copy_context.session_id
+        previsous_conv = await deps.memory.retrieve_conv(session_id)
+        if previsous_conv is not None:
+            copy_context.background = BackgroundUnit(
+                summarize=previsous_conv.summarize,
+                conversation=previsous_conv.conversation
+            )
+        return ReturnSchema(event="NEXT", context=copy_context)
+    return handle_retrieve_previous_conversation

covalve/runtime/executor/save_data.py

@@ -0,0 +1,28 @@
+from covalve.runtime.models.context import  ArgsCtx, ReturnSchema 
+from covalve.runtime.models.io import DataContent 
+from covalve.infrastructure.contract import InfrastructureRegistry
+import logging
+logger = logging.getLogger(__name__)
+
+def factory_save_data(deps:InfrastructureRegistry):
+    async def handle_save_data_to_persistence(ctx: ArgsCtx) -> ReturnSchema: 
+        session_id = ctx.context.session_id
+        data_content = DataContent(
+            session_id= session_id,
+            metadata= [unit.model_dump() for unit in ctx.context.metadata.content] if ctx.context.metadata else [],
+            user= ctx.context.query,
+            assistance= ctx.context.response.text if ctx.context.response else "",
+            traceId= ctx.context.traceId,
+            summarize= ctx.context.summarize,
+            data= ctx.context.tools_data
+        )
+        try:
+            await deps.memory.save_conv(data_content)
+        except Exception as e:
+            logger.warning("failed to save conversation traceId: %s", ctx.context.traceId)
+            logger.debug("failed metadata: %s", ctx.context.metadata.model_dump())
+        await deps.cache.delete(f"{session_id}:ANALYZE")
+        await deps.cache.delete(f"{session_id}:EXECUTE_TOOLS")
+
+        return ReturnSchema(event="NEXT", context=ctx.context)
+    return handle_save_data_to_persistence

covalve/runtime/executor/tools_executor.py

@@ -0,0 +1,65 @@
+from covalve.runtime.models.context import  ArgsCtx, ReturnSchema
+from covalve.infrastructure.contract import InfrastructureRegistry
+import asyncio
+import json
+
+
+
+
+def factory_execute_tools(deps:InfrastructureRegistry):
+
+    def _get_context_for_tool(tool_name: str, metadata_content: list, tools_schema: dict) -> str:
+        tool_intents = tools_schema[tool_name]["intent"]
+        relevant = [
+            unit.composition_context 
+            for unit in metadata_content 
+            if unit.intent in tool_intents
+        ]
+        return " | ".join(relevant) if relevant else ""
+
+
+
+    async def handle_execute_tools(ctx: ArgsCtx) -> ReturnSchema:
+        tools_schema = ctx.schema_colls.tools_schema
+        copy_context = ctx.context.model_copy(deep=True)
+        priority_group = copy_context.tool_list
+        is_break = False
+        event = "NEXT"
+        copy_context.tools_data = copy_context.tools_data or {}
+        for current_priority in sorted(priority_group):
+            tools = priority_group[current_priority]
+            tools_to_run = [
+                t for t in tools
+                if t["name"] not in copy_context.executed_tools.skipped_tools
+                and t["name"] not in copy_context.executed_tools.success_tools
+            ]
+            results = await asyncio.gather(*[
+                deps.tools.retrieve(tool["name"], {
+                    "question":copy_context.metadata.raw_query,
+                    "context": _get_context_for_tool(
+                    tool["name"], 
+                    copy_context.metadata.content,
+                    tools_schema
+                    ) 
+                    }) for tool in tools_to_run
+            ], return_exceptions=True)
+            for tool, result in zip(tools_to_run, results):
+                if isinstance(result, Exception):
+                    if tool["skippable"]:
+                        copy_context.executed_tools.skipped_tools.append(tool["name"])
+                        continue
+                    is_break = True
+                else:
+                    text = result.content[0].text
+                    try:
+                        data = json.loads(text)
+                    except json.JSONDecodeError:
+                        data = text
+                    copy_context.tools_data[tool["name"]] = data
+                    copy_context.executed_tools.success_tools.append(tool["name"])
+            if is_break is True:
+                event = "INTERNAL_ERROR"
+                copy_context.last_error_emitted = ctx.state
+                break
+        return ReturnSchema(event=event, context=copy_context)
+    return handle_execute_tools

covalve/runtime/executor/tools_mapper.py

@@ -0,0 +1,18 @@
+from collections import defaultdict
+from covalve.runtime.models.context import  ArgsCtx, ReturnSchema 
+from covalve.infrastructure.contract import InfrastructureRegistry
+
+def factory_tools_mapper(deps: InfrastructureRegistry):
+    async def handle_tools_mapper(ctx: ArgsCtx) -> ReturnSchema: 
+        tools_schema = ctx.schema_colls.tools_schema
+        copy_context = ctx.context.model_copy(deep=True)
+        content = copy_context.metadata.content
+        priority_groups = defaultdict(list)
+        for tool_name, tool_config in tools_schema.items():
+            for intent in content:
+                if intent.intent in tool_config["intent"]:
+                    priority_groups[tool_config["priority"]].append({"name": tool_name, "skippable": tool_config["skippable"]})
+                    break
+        copy_context.tool_list = dict(priority_groups)
+        return ReturnSchema(event="NEXT", context=copy_context)
+    return handle_tools_mapper

covalve/runtime/hook/__init__.py

@@ -0,0 +1,4 @@
+from covalve.runtime.hook.registry import HookRegistry
+from covalve.runtime.hook.context import ReadOnlyContext
+
+hooks = HookRegistry()

covalve/runtime/hook/context.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, ConfigDict
+from covalve.runtime.models.context import PipelineContext
+
+class ReadOnlyContext(PipelineContext):
+    model_config = ConfigDict(frozen=True)
+
+class HookReturn(BaseModel):
+    intercepted: bool
+    to: str
+    error: str
+    event:str

covalve/runtime/hook/executor.py

@@ -0,0 +1,32 @@
+from covalve.runtime.models.context import PipelineContext, STOP
+from covalve.runtime.hook.context import ReadOnlyContext,HookReturn
+import asyncio
+
+
+async def hook_executor(on:str, states, cur_state, hooks: dict, ctx:PipelineContext) -> HookReturn:
+    observe_hook = hooks["observer"][on][cur_state]
+    intercept_hook = hooks["interceptor"][on][cur_state]
+
+    copy_context = ReadOnlyContext(**ctx.model_copy(deep=True).model_dump())
+    
+    res = HookReturn(intercepted=False, to="", error="", event="")
+    
+    for fn in observe_hook:
+        asyncio.create_task(fn(copy_context))
+    
+    for on_false, fn in intercept_hook:
+        try:
+            result = await fn(copy_context)
+
+            if not result: 
+                res.intercepted = True
+                res.to = states[cur_state]["transitions"][on_false]["to"]
+                res.event = on_false
+                break
+        except Exception as e:
+            res.intercepted = True
+            res.to = STOP.INTERCEPTOR_ERROR
+            res.error = str(e)
+            res.event = STOP.INTERCEPTOR_ERROR
+    return res
+    

covalve/runtime/hook/registry.py

@@ -0,0 +1,43 @@
+from typing import Callable
+from pydantic import BaseModel
+from enum import Enum
+
+class HookOn(str, Enum):
+    ENTER = "enter"
+    EXIT = "exit"
+
+class ObserverConfig(BaseModel):
+    nodes: list[str]
+    on: HookOn
+
+class InterceptorConfig(BaseModel):
+    node: str
+    on: HookOn
+    on_false: str
+
+class HookRegistry:
+    def __init__(self):
+        self._observer_registry: list[tuple[ObserverConfig, Callable]] = []
+        self._interceptor_registry: list[tuple[InterceptorConfig, Callable]] = []
+
+    def observer(self, nodes: list[str], on: HookOn):
+        def decorator(fn: Callable):
+            self._observer_registry.append((ObserverConfig(nodes=nodes, on=on), fn))
+            return fn
+        return decorator
+
+    def interceptor(self, node: str, on: HookOn, on_false: str):
+        def decorator(fn: Callable):
+            self._interceptor_registry.append((InterceptorConfig(nodes=node, on=on, on_false=on_false), fn))
+            return fn
+        return decorator
+    
+    @property
+    def observer_collection(self):
+        return self._observer_registry
+
+    @property
+    def interceptor_collection(self):
+        return self._interceptor_registry
+    
+