Development of Wencis Python SDK for AI Agents
Youssef El Fajlaoui
Wencis
The Cognitive Flight Recorder & Self-Improvement Engine for AI Agent
Wencis is a production-ready async Python SDK that provides autonomous AI agents with causal reasoning tracing, trajectory optimization, draft response critiques, and meta-reasoning-guided self-improvement. It acts as both a debugger and a reinforcement-learning loop for agentic cognitive pipelines.
🚀 Key Capabilities
Causal Debugging (Causal Graph): Track agent decisions, hypotheses, and facts as a directed graph. Trace failures back to their root-cause decisions in a structured traceback tree.
Response Critic: Intercept draft responses before they are shown to the user. Evaluate them programmatically on Accuracy, Depth, and Honesty using LLM critiques.
Trajectory Optimizer: Analyze historical agent runs. Revise step categories, compress verbose tool outputs to save tokens, and recombine (splice) successful trajectories at crossover points.
Meta-Reasoning Engine: Run Ordinary Least Squares (OLS) linear regressions on agent confidence metrics, aggregate tool failures, and auto-propose actionable system prompt adjustments.
📦 Installation
âš¡ Quick Start
Here is a complete, copy-pasteable example showing how to initialize the causal graph, log an agent's failure path, and query the traceback tree to isolate the root cause:
🛠Core Components & API Usage
1. Response Critic (Self-Correction)
The
ResponseCritic evaluates draft agent responses against an internal LLM context. It enforces quality thresholds and checks for memory contradictions.2. Trajectory Optimizer (Fine-Tuning & Cleanup)
The
TrajectoryOptimizer helps clean up verbose run logs to save tokens and optimize historical execution runs.3. Meta-Reasoning Engine (Self-Improvement)
The
MetaReasoningEngine aggregates telemetry logs and fits confidence scores to an OLS regression line to identify if agent performance is decaying over time.🔌 Connecting AI Providers (LLM Client Adapters)
Wencis requires an object conforming to the
LLMClient protocol (specifically containing a complete_json method) to power the Critic, Optimizer, and Meta-Reasoning modules. You can wrap your existing agent LLM client in a small adapter.Here are copy-pasteable adapters for the top providers and models in 2026:
1. OpenAI / GPT-5.5
2. Anthropic / Claude Sonnet 5
3. DeepSeek / DeepSeek V4 Pro
🛡 Security & Design Standards
Cryptographic Verification: Every epistemic node contains a SHA-256 integrity hash covering its
node_id, session_id, run_id, type, content, provenance, timestamp, and metadata. Modifying any database parameter renders the node invalid under verify_integrity().Task-Serialized Connection Lock: SQLiteBackend uses reentrant asyncio locks combined with Task-ownership verification to guarantee absolute transaction isolation across concurrent tasks.
Like this project
Posted Jul 7, 2026
Developed Wencis, a Python SDK for AI agents, enhancing debugging and self-improvement.
