covalve 0.1.0__tar.gz

covalve-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.*
+cm-auto-global_truststore.jks
+ImpalaJDBC41.jar
+__pycache__/
+UI/
+mcpserver
+log/
+implement/
+covalve/infrastructure/registry.py
+jsonSchema/
+prompt/
+config/
+dist/

covalve-0.1.0/ADR/ADR-001.md

@@ -0,0 +1,57 @@
+# ADR-001: FSM-Based Pipeline Runtime
+
+## Status
+#Accepted
+
+## Date
+2026-05-06
+
+## Context
+When building an AI pipeline, several existing frameworks were evaluated,
+including LangChain, LlamaIndex, and Haystack.
+These frameworks are generally prompt-driven — routing, tool selection,
+and decision-making are delegated to the LLM automatically. This approach
+reduces the system's locus of control because control resides primarily in
+the prompt rather than in the system itself.
+
+The probabilistic and automated nature of routing makes pipeline behavior
+difficult to predict and verify, even when additional stabilization
+techniques are applied.
+
+## Decision
+Build a fully controllable, code-based orchestrator using a Deterministic
+Finite Automaton (DFA) as the foundation of the pipeline runtime.
+
+## Rationale
+A DFA was chosen because it more accurately represents the execution
+lifecycle of the pipeline compared to alternatives such as simple function
+chains or DAG-based orchestration.
+
+A DAG is inherently directional and does not naturally represent retry,
+fallback, and error recovery behaviors, which are essential parts of this
+pipeline's execution lifecycle. A DFA enables explicit states,
+deterministic transitions, and a fully traceable lifecycle from start to
+finish.
+
+Compared to prompt-based frameworks, this approach provides full system
+control — routing, error handling, and decision-making are implemented in
+code rather than delegated to prompts. As a result, pipeline behavior
+becomes predictable and verifiable because every state and transition is
+defined explicitly.
+
+## Consequences
+
+### Positive
+- Pipeline behavior is fully deterministic and auditable
+- Error handling is explicit — every failure case has a defined execution path
+- No dependency on external orchestration frameworks
+- Easier tracing and debugging because every state transition is recorded
+
+### Negative
+- More complex developer experience — contributors must understand
+  state machines and pipeline design before contributing
+- Less accessible for non-developers — there is no visual interface like
+  n8n or LangFlow for inspecting or modifying flows
+- No real-time activity graph visualization
+- Flow changes require updates to schemas and executors rather than
+  simply modifying prompts

covalve-0.1.0/ADR/ADR-002.md

@@ -0,0 +1,63 @@
+# ADR-002: Python as Implementation Language
+
+## Status
+#Accepted
+
+## Date
+2026-05-06
+
+## Context
+ml-runtime requires an implementation language that can integrate directly
+with the AI ecosystem — including LLM SDKs, embedding models, and vector
+stores.
+
+The architectural foundation of ml-runtime traces back to StateFlowGuard,
+a TypeScript library built previously. However, the decision to use
+TypeScript/Node.js was never under consideration for ml-runtime — Python
+was the baseline assumption from the start given its AI ecosystem maturity.
+
+Rust was identified as the ideal systems language for a runtime of this
+nature due to its memory safety guarantees, lack of GC, and true
+parallelism. However, at this stage, the cost of integrating Rust with
+the Python AI ecosystem outweighs the benefit. Rust AI clients are
+largely community-maintained, and FFI boundary complexity via PyO3 adds
+significant overhead for a project still in the pilot phase.
+
+Python was chosen as the pragmatic baseline.
+
+## Decision
+Implement ml-runtime in Python, using asyncio as the concurrency model
+and Pydantic for schema validation and typed context objects.
+
+## Rationale
+Python is the native language of the AI ecosystem. LLM SDKs, vector
+stores, and embedding libraries all provide first-class Python support.
+This eliminates integration friction at the AI layer.
+
+asyncio provides sufficient concurrency for I/O-bound pipeline workloads
+— LLM calls, vector store queries, and storage reads are all I/O-bound
+operations where asyncio performs well.
+
+Pydantic enforces schema contracts at runtime, partially mitigating
+Python's lack of compile-time type enforcement.
+
+## Consequences
+
+### Positive
+- Full compatibility with AI ecosystem libraries out of the box
+- asyncio handles I/O-bound concurrency adequately for pipeline workloads
+- Pydantic provides runtime type safety for PipelineContext and schemas
+
+### Negative
+- GIL prevents true parallelism — CPU-bound executor work will block
+  other coroutines unless explicitly offloaded via run_in_executor()
+- GC pressure increases under high request volume due to Pydantic object
+  churn per pipeline execution
+- Python's dynamic typing requires disciplined use of type hints and
+  Pydantic — enforcement is opt-in, not compile-time
+
+## Future Consideration
+Rust via PyO3 is the identified migration path if GIL or GC pressure
+becomes a measurable bottleneck in production. The FSM core is a natural
+candidate for extraction as a native extension while the Python AI layer
+remains in place.

covalve-0.1.0/ADR/ADR-003.md

@@ -0,0 +1,112 @@
+# ADR-003: Hook System Design
+
+## Status
+#Accepted
+
+## Date
+2026-05-19
+
+## Context
+As the runtime matured, there was a need to accommodate cross-cutting concerns
+such as state transition logging, audit trails, and notifications without
+coupling these concerns into executor logic. Executors should remain focused
+on their single responsibility — processing a state and returning an event.
+
+Hardcoding observability and extensibility logic directly into executors would
+violate separation of concerns and make the runtime harder to maintain and extend.
+
+The initial design used a `plugins.json` configuration file with two modes:
+`hanging` (fire-and-forget) and `middleware` (blocking). After implementation,
+this approach was replaced with a decorator-based `HookRegistry` for the
+following reasons:
+
+- `plugins.json` separates hook registration from hook implementation — a
+  contributor must read two files to understand one hook's behavior
+- Decorator-based registration is more idiomatic in Python and easier to
+  trace via type checkers and IDE tooling
+- The names `hanging` and `middleware` did not sufficiently express the
+  behavioral contract of each mode
+
+## Decision
+Introduce a hook system implemented via a decorator-based `HookRegistry`
+with two hook types: **observer** and **interceptor**.
+
+### Observer
+Fire-and-forget. Can be attached to multiple nodes. Executed via
+`asyncio.create_task()`. Used for observability concerns such as logging,
+metrics, and audit trails that must not block pipeline execution.
+
+```python
+@hooks.observer(nodes=["ANALYZE", "MAIN_LLM"], on=HookOn.EXIT)
+async def fn(ctx: ReadOnlyContext) -> None:
+    ...
+```
+
+### Interceptor
+Blocking. Single node only. Executed via `await`. Returns `bool` — if
+`False`, the runtime emits the `on_false` event and redirects accordingly.
+Used for concerns that must intercept execution before or after a node runs
+and may need to halt or redirect the pipeline.
+
+```python
+@hooks.interceptor(node="GUARDRAIL", on=HookOn.ENTER, on_false="OUT_OF_SCOPE")
+async def fn(ctx: ReadOnlyContext) -> bool:
+    ...
+```
+
+`on_false` is **required** on every interceptor. If no redirect is needed,
+use an observer instead.
+
+### Single-node constraint on interceptor
+Interceptor is constrained to a single node because each node may have a
+different set of valid outgoing events. Allowing multi-node interceptors
+would require one `on_false` event to be valid across all attached nodes
+simultaneously — this cannot be guaranteed and would produce ambiguous
+wiring between nodes and their `on_false` transitions. The single-node
+constraint removes this ambiguity entirely.
+
+### ReadOnlyContext
+All hooks receive a `ReadOnlyContext` — a subclass of `PipelineContext`
+with `frozen=True`. Hooks observe pipeline state; they do not modify it.
+This ensures hook side effects are bounded and cannot corrupt context.
+
+### Startup validation
+`init_hooks()` validates all registered `on_false` events against the
+schema transitions at startup. An interceptor whose `on_false` event is
+not a valid transition in `schema.json` will raise an error before the
+pipeline accepts any request.
+
+## Rationale
+Hooks as a separate concern from executors keeps the core runtime clean.
+Observability and extensibility are opt-in — implementors attach only what
+they need without modifying executor code.
+
+The event-based redirect mechanism for interceptors preserves graph
+integrity. Interceptors cannot redirect to arbitrary nodes — they can only
+emit events already defined in the schema, enforced at startup. This keeps
+the FSM fully auditable.
+
+`ReadOnlyContext` as the hook interface ensures that hook side effects are
+predictable. Hooks observe state; they do not modify it.
+
+Decorator-based registration keeps registration and implementation
+co-located, reducing the cognitive overhead of understanding any given hook.
+
+## Consequences
+
+### Positive
+- Observability concerns are decoupled from executor logic
+- Implementors extend runtime behavior without touching core files
+- Graph integrity is preserved — hooks cannot bypass schema-defined transitions
+- Single-node constraint on interceptor eliminates `on_false` wiring ambiguity
+- `on_false` startup validation catches misconfiguration before runtime
+- Decorator-based registration is co-located with implementation — easier to read and trace
+
+### Negative
+- Additional complexity for contributors — hook lifecycle, observer vs interceptor
+  distinction, and `on_false` requirements must be understood before use
+- Interceptors add latency to the nodes they are attached to
+- `on_false` events must be explicitly defined in `schema.json` — implementors
+  must keep hook registrations and schema in sync
+- Single-node interceptor constraint means multi-node interception requires
+  registering separate interceptors per node

covalve-0.1.0/ADR/ADR-004.md

@@ -0,0 +1,96 @@
+# ADR-004: Guardrail as an Optional Core Node
+
+## Status
+#Accepted
+
+## Date
+2026-05-19
+
+## Context
+The pipeline's ANALYZE state is responsible for classifying user queries into
+structured intents. During development, domain boundary enforcement — rejecting
+queries outside the operational scope of the runtime — was initially handled
+inside ANALYZE by prompting the LLM to assign low confidence or an
+`outofcontext` intent to out-of-scope queries.
+
+This approach has several drawbacks:
+
+- ANALYZE becomes responsible for two distinct concerns: intent classification
+  and domain boundary enforcement. This violates single responsibility.
+- Domain context injected into the ANALYZE prompt increases token count on every
+  request, regardless of whether the query is out of scope.
+- LLM-based boundary enforcement is probabilistic — as observed in testing,
+  out-of-scope queries occasionally pass through and receive full responses.
+- Cost and latency scale with prompt size. Overloading ANALYZE with domain
+  guardrail logic compounds this as the domain context grows.
+
+## Decision
+Introduce a dedicated GUARDRAIL node as an optional core node, positioned
+between `RETRIEVE_PREVIOUS_CONVERSATION` and `ANALYZE` in the pipeline graph
+when included.
+
+GUARDRAIL is optional — its presence is declared in `schema.json`. If the
+node is absent from the schema, the runtime proceeds directly from
+`RETRIEVE_PREVIOUS_CONVERSATION` to `ANALYZE` without error.
+
+When included, GUARDRAIL's implementation is injected via a `GuardrailBase`
+abstract interface defined in `infrastructure/adapters/`, following the same
+pattern as `LLMBase` and `StorageBase`. The core runtime does not know the
+domain rules — only that a guardrail check must pass before ANALYZE is invoked.
+
+Graph with GUARDRAIL included:
+```
+RETRIEVE_PREVIOUS_CONVERSATION → GUARDRAIL → ANALYZE
+                                    ↓
+                                FALLBACK (OUT_OF_SCOPE)
+```
+
+Graph without GUARDRAIL:
+```
+RETRIEVE_PREVIOUS_CONVERSATION → ANALYZE
+```
+The short-term mitigation — handling `outofcontext` via domain prompt in
+`main_llm_response.txt` — remains in place until GUARDRAIL is implemented.
+
+## Rationale
+Schema-driven optionality is made reliable by ADR-005 — because every executor
+is a pure function that returns a new context via `model_copy` rather than
+mutating the received instance, nodes can be added or removed from the graph
+without implicit side effects on downstream nodes.
+
+GUARDRAIL is optional because not every deployment context requires the same
+boundary enforcement strategy. A prototype or internal tool may have no
+out-of-scope risk, and forcing a mandatory node would add unnecessary
+implementation burden. The core remains agnostic.
+
+Despite being optional, GUARDRAIL is strongly recommended for any production
+deployment. LLM-based boundary enforcement in ANALYZE is probabilistic — as
+observed in testing, out-of-scope queries occasionally bypass prompt-level
+filtering. GUARDRAIL provides a deterministic enforcement layer before any
+LLM call, at zero token cost.
+
+The `GuardrailBase` interface keeps the core agnostic to implementation
+strategy. Whether the implementor uses keyword matching, embedding similarity,
+or a rule engine is an implementation detail the core does not need to know.
+
+## Consequences
+
+### Positive
+- ANALYZE is responsible only for intent classification
+- Out-of-scope queries are rejected before any LLM call — zero token cost
+- Schema-driven optionality is preserved — GUARDRAIL can be included or
+  excluded via `schema.json` without affecting other nodes
+- Core remains agnostic to business domain and enforcement strategy
+
+### Negative
+- Optional status means production deployments may omit GUARDRAIL — the
+  runtime will not warn or block if the node is absent
+- When included, adds one additional state to every pipeline execution,
+  including in-scope queries
+- Implementors must understand that omitting GUARDRAIL delegates boundary
+  enforcement back to ANALYZE prompts, which is probabilistic
+
+## Recommendation
+Production deployments should always include GUARDRAIL. Omitting it is
+only appropriate for prototypes or internal tools where domain boundary
+enforcement is not a requirement.

covalve-0.1.0/ADR/ADR-005.md

@@ -0,0 +1,104 @@
+# ADR-005: No Direct Mutation of PipelineContext
+
+## Status
+#Accepted
+
+## Date
+2026-05-21
+
+## Context
+`PipelineContext` is the primary communication object passed between nodes
+in the pipeline. It carries the accumulated results of each executor to
+the next state in the graph.
+
+During the pilot phase, executors were written to mutate `PipelineContext`
+directly:
+
+```python
+ctx.context.metadata = metadata
+ctx.context.is_clarification = True
+ctx.context.tools_data = {}
+```
+
+This approach works functionally but violates the intent of how nodes should
+interact with context. Direct mutation introduces several risks:
+
+- Executors can overwrite fields set by previous nodes without explicit intent
+- Side effects are implicit — it is not clear from the function signature
+  what a node will change
+- Node behavior becomes order-dependent in ways that are not visible in the
+  schema, making the pipeline harder to reason about
+- Schema-driven optionality — the ability to compose pipelines by including
+  or excluding nodes via `schema.json` — is fragile if nodes have implicit
+  side effects on shared state
+
+This principle is foundational to ADR-004 (Guardrail as Optional Node).
+Schema-driven optionality only works reliably if every node is a pure
+function — same input context produces predictable output context, with no
+hidden side effects on the received instance.
+
+## Decision
+Executors must not mutate the `PipelineContext` instance they receive.
+Instead, every executor must return a new context instance via Pydantic's
+`model_copy(update={...})` pattern.
+
+```python
+# before — direct mutation
+ctx.context.metadata = metadata
+return ReturnSchema(event="NEXT", context=ctx.context)
+
+# after — return new instance
+return ReturnSchema(
+    event="NEXT",
+    context=ctx.context.model_copy(update={"metadata": metadata})
+)
+```
+
+`PipelineContext` remains a mutable Pydantic model — this is not full
+immutability. The constraint is behavioral: no executor may call attribute
+assignment on the context instance it receives. All changes must go through
+`model_copy`.
+
+## Rationale
+`PipelineContext` is a message passed between nodes, not a shared global
+state. Treating it as a message means each node is responsible for producing
+the next version of that message explicitly — changes are visible in the
+return value, not hidden as side effects.
+
+This aligns with the functional pipeline principle: nodes are pure functions
+that take context and return context. The FSM runtime loop is the only
+entity that decides which context version becomes the active state.
+
+This also enables schema-driven optionality — if a node can be added or
+removed from the graph via `schema.json` without breaking other nodes,
+each node must be self-contained and free of implicit dependencies on
+mutation order.
+
+## Consequences
+
+### Positive
+- Node behavior is explicit — all context changes are visible in the return value
+- Nodes become self-contained — removing a node from the schema does not
+  silently break downstream nodes that depended on its mutations
+- Easier to test — each executor can be tested in isolation with a fixed
+  input context
+- Enables schema-driven optionality as described in ADR-004
+
+### Negative
+- All existing executors need to be refactored — direct mutations are
+  pervasive in the current codebase
+- `model_copy` creates a new Pydantic object per executor call — minor
+  memory overhead per pipeline execution, acceptable at current scale
+- Slightly more verbose executor code compared to direct assignment
+
+## Refactor Scope
+The following executors require refactoring as part of Phase 2:
+- `handle_analyze` — mutates `metadata`, `error`, `last_error_emitted`
+- `handle_fallback` — mutates `is_clarification`, `fallback_content`
+- `handle_tools_mapper` — mutates `tool_list`
+- `handle_execute_tools` — mutates `tools_data`, `tool_list`, `last_error_emitted`
+- `handle_main_llm` — mutates `summarize`, `response`
+- `handle_save_data_to_persistence` — no context mutation, compliant
+- `handle_retrieve_previous_conversation` — mutates `background`
+- `handle_error_counter` — mutates via redis, context passed through
+- `handle_internal_server_error` — mutates `response`

covalve-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Candra Julius Indira Patty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.