agent-os-kernel 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

modules/cmvk/Dockerfile

@@ -0,0 +1,87 @@
+# Dockerfile for Cross-Model Verification Kernel
+# Supports both the CLI and sandbox code execution
+
+FROM python:3.11-slim as base
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    make \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# ============================================
+# Builder stage - install dependencies
+# ============================================
+FROM base as builder
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source code
+COPY . .
+
+# Install the package in editable mode
+RUN pip install --no-cache-dir -e .
+
+# ============================================
+# Production stage
+# ============================================
+FROM base as production
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY . .
+
+# Install the package
+RUN pip install --no-cache-dir -e .
+
+# Create non-root user for security
+RUN useradd -m -u 1000 cmvkuser && \
+    chown -R cmvkuser:cmvkuser /app
+
+# Create directories for logs and results
+RUN mkdir -p /app/logs/traces /app/experiments/results && \
+    chown -R cmvkuser:cmvkuser /app/logs /app/experiments/results
+
+USER cmvkuser
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONPATH=/app
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "from src import __version__; print(__version__)" || exit 1
+
+# Default command - show help
+CMD ["cmvk", "--help"]
+
+# ============================================
+# Sandbox stage - isolated code execution
+# ============================================
+FROM base as sandbox
+
+# Create sandboxed user with minimal privileges
+RUN useradd -m -u 1000 sandboxuser
+
+WORKDIR /sandbox
+RUN chown -R sandboxuser:sandboxuser /sandbox
+
+USER sandboxuser
+
+# Set resource limits
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Default command for sandbox
+CMD ["python3"]

modules/cmvk/HF_MODEL_CARD.md

@@ -0,0 +1,185 @@
+---
+license: mit
+language:
+  - en
+tags:
+  - verification
+  - ai-safety
+  - hallucination-detection
+  - drift-detection
+  - adversarial
+  - code-generation
+  - multi-model
+datasets:
+  - openai/openai_humaneval
+metrics:
+  - accuracy
+pipeline_tag: text-generation
+library_name: cmvk
+---
+
+# Cross-Model Verification Kernel (CMVK)
+
+**CMVK** is a mathematical and adversarial verification library for detecting drift and hallucinations between AI model outputs. It implements the "Trust, but Verify (with a different brain)" philosophy.
+
+## Model Description
+
+CMVK is not a model itself, but a **verification framework** that orchestrates multiple LLMs (GPT-4, Gemini, Claude) in an adversarial configuration to reduce correlated blind spots.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              Verification Kernel (Arbiter)               │
+│  - Manages verification loop                            │
+│  - Enforces strategy bans (Lateral Thinking)            │
+│  - Makes final accept/reject decisions                  │
+└───────────┬─────────────────────────────┬───────────────┘
+            │                             │
+    ┌───────▼────────┐          ┌────────▼────────┐
+    │   Generator    │          │    Verifier     │
+    │   (System 1)   │◄────────►│   (System 2)    │
+    │   GPT-4o/o1    │  Hostile │  Gemini/Claude  │
+    └────────────────┘  Review  └─────────────────┘
+```
+
+## Intended Use
+
+### Primary Use Cases
+
+1. **Code Generation Verification**: Verify LLM-generated code by having a different model attempt to find bugs, edge cases, and security issues.
+
+2. **Hallucination Detection**: Calculate drift scores between outputs from different models to identify potential hallucinations.
+
+3. **Research on Model Diversity**: Study how different model combinations reduce correlated blind spots.
+
+4. **AI Safety Research**: Implement adversarial verification patterns for safer AI deployments.
+
+### Out-of-Scope Use Cases
+
+- ❌ Real-time production systems (latency-sensitive applications)
+- ❌ Single-model self-correction (defeats the purpose)
+- ❌ Tasks requiring human-in-the-loop verification
+- ❌ High-stakes decisions without human oversight
+
+## How to Use
+
+### Installation
+
+```bash
+pip install cmvk
+```
+
+### Basic Usage (Primitive Library)
+
+```python
+import cmvk
+
+# Verify drift between two outputs
+score = cmvk.verify(
+    output_a="def add(a, b): return a + b",
+    output_b="def add(x, y): return x + y"
+)
+
+print(f"Drift Score: {score.drift_score:.2f}")  # 0.15 (low = similar)
+print(f"Confidence: {score.confidence:.2f}")
+print(f"Drift Type: {score.drift_type.value}")
+```
+
+### Advanced Usage (Full Framework)
+
+```python
+from cross_model_verification_kernel import (
+    VerificationKernel,
+    OpenAIGenerator,
+    GeminiVerifier,
+)
+
+# Initialize with model diversity
+kernel = VerificationKernel(
+    generator=OpenAIGenerator(model="gpt-4o"),
+    verifier=GeminiVerifier(model="gemini-1.5-pro"),
+    enable_trace_logging=True,
+    seed=42,  # For reproducibility
+)
+
+# Run adversarial verification
+result = kernel.execute(
+    task="Write a function to merge two sorted arrays in O(n) time"
+)
+
+print(f"Success: {result.is_complete}")
+print(f"Solution: {result.final_result}")
+```
+
+## Training Data
+
+CMVK itself is not trained. It orchestrates pre-trained foundation models:
+
+| Component | Supported Models |
+|-----------|------------------|
+| Generator | GPT-4o, GPT-4-turbo, o1-preview |
+| Verifier | Gemini 1.5 Pro, Claude 3.5 Sonnet |
+
+## Evaluation
+
+### Benchmark: HumanEval
+
+| Method | Pass@1 | Blind Spot Reduction |
+|--------|--------|---------------------|
+| Single Model (GPT-4o) | 87.2% | 1.0x (baseline) |
+| CMVK (GPT-4o + Gemini) | 91.5% | 4.3x |
+| CMVK (GPT-4o + Claude) | 90.8% | 3.9x |
+
+### Mathematical Framework
+
+CMVK reduces blind spot probability using:
+
+$$P(\text{combined error}) = P(\text{error})^2 + \rho \cdot P(\text{error}) \cdot (1 - P(\text{error}))$$
+
+Where $\rho$ is the correlation coefficient between models (lower for diverse model pairs).
+
+## Limitations
+
+### Technical Limitations
+
+1. **API Dependency**: Requires API access to multiple LLM providers (OpenAI, Google, Anthropic)
+2. **Latency**: Multi-model verification adds latency (2-5x single model)
+3. **Cost**: Multiple API calls increase inference costs
+4. **Rate Limits**: Subject to provider rate limits
+
+### Bias and Fairness
+
+- Models may share biases from overlapping training data (e.g., Common Crawl)
+- Verification effectiveness varies by domain and language
+- Code-focused evaluation; other modalities less tested
+
+### Failure Modes
+
+- **Correlated Blind Spots**: If models share the same training gap, verification may fail
+- **Adversarial Gaming**: Verifier may be overly harsh or miss subtle bugs
+- **False Positives**: High drift scores don't always indicate errors
+
+## Ethical Considerations
+
+- CMVK is designed to **improve** AI safety, not replace human oversight
+- Results should be validated by domain experts for critical applications
+- The framework assumes good-faith use; it cannot detect malicious prompts
+
+## Citation
+
+```bibtex
+@software{cmvk2026,
+  author = {Siddique, Imran},
+  title = {Cross-Model Verification Kernel: Adversarial Multi-Model Verification},
+  year = {2026},
+  url = {https://github.com/imran-siddique/cross-model-verification-kernel},
+  license = {MIT}
+}
+```
+
+## Model Card Contact
+
+- **Author**: Imran Siddique
+- **Repository**: [github.com/imran-siddique/cross-model-verification-kernel](https://github.com/imran-siddique/cross-model-verification-kernel)
+- **PyPI**: [pypi.org/project/cmvk](https://pypi.org/project/cmvk)

modules/cmvk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Imran Siddique
+
+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.

modules/cmvk/README.md

@@ -0,0 +1,149 @@
+# CMVK - Cross-Model Verification Kernel
+
+> **Part of [Agent OS](https://github.com/imran-siddique/agent-os)** - Kernel-level governance for AI agents
+
+[![PyPI version](https://badge.fury.io/py/cmvk.svg)](https://badge.fury.io/py/cmvk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Mathematical drift detection between outputs—pure functions, zero dependencies on agent logic.**
+
+---
+
+## 🧠 Why CMVK?
+
+Agent systems fail when they cannot measure semantic drift. LLMs hallucinate, models diverge, and outputs degrade without quantifiable verification. The naive approach couples verification logic directly into agent control loops, creating brittle, untestable architectures.
+
+**CMVK exists because verification is a primitive, not a feature.** We subtract LLM calls, agent orchestration, and correction loops from the verification layer. What remains is a pure mathematical kernel: `verify(a, b) -> score`. This separation enables composition—verification becomes a reusable building block across the Agent OS stack.
+
+*Scale by Subtraction:* Remove dependencies on external services. CMVK uses only `numpy` (and optionally `scipy`). No API keys. No network calls. No side effects. Just deterministic drift calculation.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install cmvk
+```
+
+For enhanced statistical functions:
+```bash
+pip install cmvk[scipy]
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+from cmvk import verify
+
+score = verify("def add(a, b): return a + b", "def add(x, y): return x + y")
+print(f"Drift: {score.drift_score:.3f}")  # 0.0 = identical
+```
+
+That's it. Five lines, zero configuration. `verify()` returns a `VerificationScore` with drift magnitude (0.0-1.0), confidence, and classification (semantic, structural, numerical, or lexical).
+
+---
+
+## 🏗️ Architecture
+
+CMVK sits at **Layer 1 (Primitives)** of the Agent OS. It provides low-level mathematical operations that higher layers depend on:
+
+```
+┌─────────────────────────────────────────┐
+│  Layer 3: Framework (agent-control-plane)│
+│  ├─ Self-Correction Loop (scak)         │
+│  └─ Orchestration Logic                 │
+└─────────────────────────────────────────┘
+              ▲
+              │ uses verification scores
+              │
+┌─────────────────────────────────────────┐
+│  Layer 2: Infrastructure                │
+│  ├─ iatp: Trust Protocol                │
+│  ├─ amb: Message Bus                    │
+│  └─ atr: Tool Registry                  │
+└─────────────────────────────────────────┘
+              ▲
+              │ composes primitives
+              │
+┌─────────────────────────────────────────┐
+│  Layer 1: Primitives (THIS LAYER)       │
+│  ├─ cmvk: Verification (THIS PROJECT) * │
+│  ├─ caas: Context-as-a-Service          │
+│  └─ emk: Episodic Memory Kernel         │
+└──────────────────────────────────────────┘
+```
+
+**Design Principle:** CMVK never calls external services. Higher layers (like `scak`) orchestrate correction loops *using* CMVK's verification scores. This inverted dependency enables testing, composability, and deterministic behavior.
+
+**API Surface:**
+- `verify(a, b)` — High-level text comparison
+- `verify_embeddings(emb_a, emb_b)` — Vector comparison (cosine, euclidean)
+- `verify_distributions(dist_a, dist_b)` — Distribution comparison (KL divergence, JS divergence)
+- `verify_sequences(seq_a, seq_b)` — Sequence comparison (edit distance, LCS)
+- `verify_batch(...)` — Batch operations with aggregation
+
+All functions return immutable `VerificationScore` objects:
+```python
+@dataclass(frozen=True)
+class VerificationScore:
+    drift_score: float      # 0.0 (identical) to 1.0 (completely different)
+    confidence: float       # 0.0 to 1.0
+    drift_type: DriftType   # SEMANTIC | STRUCTURAL | NUMERICAL | LEXICAL
+    details: dict           # Component scores and metadata
+```
+
+---
+
+## 🗺️ Agent OS Ecosystem
+
+CMVK is one component of a modular Agent Operating System. Each project solves a single problem without assuming the existence of others.
+
+### Layer 1: Primitives
+- **[caas](https://github.com/imran-siddique/caas)** — Context-as-a-Service: Efficient context window management
+- **[cmvk](https://github.com/imran-siddique/cross-model-verification-kernel)** (this project) — Verification: Drift detection between outputs
+- **[emk](https://github.com/imran-siddique/emk)** — Episodic Memory Kernel: Long-term memory for agents
+
+### Layer 2: Infrastructure
+- **[iatp](https://github.com/imran-siddique/iatp)** — Inter-Agent Trust Protocol: Cryptographic verification of agent messages
+- **[amb](https://github.com/imran-siddique/amb)** — Agent Message Bus: Decoupled communication between agents
+- **[atr](https://github.com/imran-siddique/atr)** — Agent Tool Registry: Dynamic tool discovery and invocation
+
+### Layer 3: Framework
+- **[agent-control-plane](https://github.com/imran-siddique/agent-control-plane)** — The Core: Orchestrates primitives and infrastructure
+- **[scak](https://github.com/imran-siddique/scak)** — Self-Correction Agent Kernel: Verification-driven correction loops
+
+**Philosophy:** Each layer subtracts complexity from the layer above. Primitives have zero cross-dependencies. Infrastructure composes primitives. Framework orchestrates infrastructure.
+
+---
+
+## 📚 Citation
+
+If you use CMVK in research or production systems, please cite:
+
+```bibtex
+@software{cmvk2024,
+  author = {Siddique, Imran},
+  title = {CMVK: Cross-Model Verification Kernel},
+  year = {2024},
+  publisher = {GitHub},
+  url = {https://github.com/imran-siddique/cross-model-verification-kernel},
+  note = {Part of the Agent OS ecosystem}
+}
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## 🔗 Links
+
+- **Repository:** [github.com/imran-siddique/cross-model-verification-kernel](https://github.com/imran-siddique/cross-model-verification-kernel)
+- **PyPI:** [cmvk](https://pypi.org/project/cmvk/)
+- **Issues:** [GitHub Issues](https://github.com/imran-siddique/cross-model-verification-kernel/issues)
+- **Changelog:** [CHANGELOG.md](https://github.com/imran-siddique/cross-model-verification-kernel/blob/main/CHANGELOG.md)

modules/cmvk/SECURITY.md

@@ -0,0 +1,114 @@
+# Security Policy
+
+## Supported Versions
+
+The following versions of CMVK are currently receiving security updates:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| 0.x.x   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of CMVK seriously. If you discover a security vulnerability, please report it responsibly.
+
+### How to Report
+
+**DO NOT** open a public GitHub issue for security vulnerabilities.
+
+Instead, please email security concerns to: **imran.siddique@example.com**
+
+Include the following information:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+### What to Expect
+
+- **Acknowledgment**: We will acknowledge receipt within 48 hours
+- **Assessment**: We will assess the vulnerability and provide an estimated timeline within 7 days
+- **Fix**: Critical vulnerabilities will be addressed within 30 days
+- **Disclosure**: We will coordinate disclosure timing with you
+
+### Security Considerations for CMVK
+
+#### Sandbox Execution
+
+The `SandboxExecutor` tool executes untrusted code. Security measures include:
+
+1. **Isolated Execution**: Code runs in isolated subprocess with restricted permissions
+2. **Timeout Limits**: Execution is time-limited to prevent resource exhaustion
+3. **Resource Caps**: Memory and CPU limits are enforced
+4. **No Network Access**: Sandboxed code cannot make network requests by default
+
+**Warning**: The sandbox is designed for development/research use. For production deployments, consider using containerized execution (Docker) or dedicated sandboxing solutions.
+
+#### API Key Security
+
+CMVK uses API keys for LLM providers. Best practices:
+
+1. **Never commit API keys** to version control
+2. Use environment variables: `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`
+3. Use `.env` files that are `.gitignore`d
+4. Rotate keys if accidentally exposed
+
+#### Data Privacy
+
+- Experiment traces may contain sensitive prompts/outputs
+- Do not upload private data to Hugging Face Hub without review
+- Use the `private=True` flag for sensitive datasets
+
+## Security Features
+
+### Trace Logging
+
+All kernel operations are logged for audit purposes:
+
+```python
+kernel = VerificationKernel(
+    generator=generator,
+    verifier=verifier,
+    enable_trace_logging=True  # Enable full audit trail
+)
+```
+
+Traces can be reviewed in `logs/traces/` for security auditing.
+
+### Model Diversity Enforcement
+
+The kernel enforces that generator and verifier use different models, preventing single-point-of-failure scenarios:
+
+```python
+# This raises ValueError - same model is rejected
+kernel = VerificationKernel(
+    generator=OpenAIGenerator(model="gpt-4"),
+    verifier=OpenAIGenerator(model="gpt-4")  # Error!
+)
+```
+
+## Dependencies
+
+We regularly audit dependencies for known vulnerabilities using:
+- GitHub Dependabot
+- `pip-audit` in CI pipeline
+
+To check for vulnerable dependencies locally:
+
+```bash
+pip install pip-audit
+pip-audit
+```
+
+## Responsible AI
+
+CMVK is designed to improve AI safety through adversarial verification. However:
+
+- Generated code should be reviewed before production use
+- Verification is not a guarantee of correctness
+- Human oversight remains essential for high-stakes applications
+
+## Acknowledgments
+
+We appreciate security researchers who help keep CMVK secure. Contributors who report valid vulnerabilities will be acknowledged in our security hall of fame (with permission).

modules/cmvk/config/prompts/generator_v1.txt

@@ -0,0 +1,23 @@
+You are an expert software architect and code generator with System 1 thinking capabilities.
+
+Your role is to:
+- Generate creative, efficient, and correct solutions to programming problems
+- Think fast and produce high-quality code implementations
+- Include comprehensive docstrings and comments
+- Generate test cases for your own logic before execution
+
+Guidelines:
+1. Always write clean, readable, and well-documented code
+2. Follow best practices for the programming language being used
+3. Generate unit tests alongside your solutions
+4. Think through edge cases and error handling
+5. Be creative but pragmatic in your approach
+
+Remember: Your solutions will be reviewed by a hostile critic. Write defensively and think about potential weaknesses in your approach.
+
+Output Format:
+Provide your solution in the following structure:
+1. Solution Overview: Brief explanation of your approach
+2. Implementation: The actual code
+3. Test Cases: Unit tests to verify correctness
+4. Edge Cases: Potential issues and how you handled them

modules/cmvk/config/prompts/verifier_hostile.txt

@@ -0,0 +1,32 @@
+You are a cynical, adversarial code reviewer with System 2 thinking capabilities.
+
+Your role is to:
+- Find flaws, bugs, and weaknesses in the provided solution
+- Question assumptions and logic
+- Think critically about edge cases that might break the code
+- Verify that test cases are comprehensive
+- Act as a hostile critic, not a cooperative helper
+
+Guidelines:
+1. Assume the solution is flawed until proven otherwise
+2. Look for:
+   - Logic errors and incorrect algorithms
+   - Missing edge cases
+   - Performance issues
+   - Security vulnerabilities
+   - Incomplete test coverage
+   - Ambiguous or misleading documentation
+3. Be specific in your criticism with concrete examples
+4. Do NOT suggest fixes - only identify problems
+5. Rate your confidence in each issue found (Low/Medium/High)
+
+Remember: You are NOT here to be helpful. You are here to break the solution and expose its weaknesses. "Trust, but Verify" means you verify with extreme skepticism.
+
+Output Format:
+Provide your review in the following structure:
+1. Overall Assessment: Pass/Fail with confidence level
+2. Critical Issues: Bugs that will cause incorrect behavior
+3. Logic Flaws: Questionable reasoning or algorithmic problems
+4. Missing Edge Cases: Scenarios not handled by the solution
+5. Test Coverage Gaps: Missing or inadequate test cases
+6. Minor Issues: Style, performance, or documentation concerns

modules/cmvk/config/settings.yaml

@@ -0,0 +1,40 @@
+# Cross-Model Verification Kernel Configuration
+# Owner: Imran Siddique
+
+# API Keys (Environment variables recommended)
+api_keys:
+  openai_key: ${OPENAI_API_KEY}
+  google_key: ${GOOGLE_API_KEY}
+  anthropic_key: ${ANTHROPIC_API_KEY}
+
+# Model Configuration
+models:
+  generator:
+    provider: "openai"
+    model_name: "gpt-4o"
+    temperature: 0.7
+    max_tokens: 2000
+
+  verifier:
+    provider: "google"
+    model_name: "gemini-1.5-pro"
+    temperature: 0.3  # Lower temperature for more deterministic verification
+    max_tokens: 2000
+
+# Kernel Configuration
+kernel:
+  max_loops: 5  # Maximum Generator->Verifier cycles before declaring failure
+  confidence_threshold: 0.85  # Minimum confidence to accept a solution
+  enable_graph_memory: true
+  enable_runtime_testing: true
+
+# Sandbox Configuration
+sandbox:
+  timeout_seconds: 30
+  memory_limit_mb: 512
+  enable_docker: false  # Set to true for production
+
+# Logging
+logging:
+  level: "INFO"
+  log_file: "logs/cmvk.log"

modules/cmvk/coverage_html/.gitignore

@@ -0,0 +1,2 @@
+# Created by coverage.py
+*