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

modules/scak/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to the Self-Correcting Agent Kernel (SCAK) project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-01-18
+
+### Added
+- Real LLM integrations (OpenAI GPT-4o, o1-preview, Anthropic Claude 3.5 Sonnet)
+- Multi-agent orchestration framework with supervisor, analyst, and verifier roles
+- Dynamic tool registry with multi-modal support (text, vision, audio, code)
+- Advanced security and governance layer with ML-based threat detection
+- Constitutional AI principles enforcement
+- Red-team security benchmark (60+ adversarial prompts)
+- Streamlit dashboard for real-time monitoring and visualization
+- CLI tool (`scak`) for agent management and benchmarks
+- Docker Compose setup for production deployment
+- Comprehensive research citations throughout codebase
+- Production features demo showcasing all capabilities
+
+### Enhanced
+- Shadow Teacher implementation with o1-preview reasoning traces
+- Memory Controller with write-through protocol
+- Telemetry system with structured JSON logging
+- Test suite expanded to 183+ tests
+- Documentation with detailed research foundations
+
+### Fixed
+- Async/await patterns for non-blocking I/O throughout
+- Type safety with Pydantic v2 models
+- Error handling with structured telemetry (no silent failures)
+
+## [1.0.0] - 2026-01-15
+
+### Added
+- Dual-Loop Architecture (Runtime Safety + Alignment Engine)
+- Completeness Auditor for laziness detection
+- Shadow Teacher diagnostic agent
+- Semantic Purge mechanism with Type A/B decay taxonomy
+- Three-tier memory hierarchy (Kernel → Skill Cache → Archive)
+- Triage Engine for sync/async routing
+- Agent Patcher with rollback support
+- SkillMapper for tool-lesson correlation
+- Rubric system for lesson scoring
+- Phase 3 Memory Lifecycle implementation
+
+### Experiments
+- GAIA Benchmark for laziness detection (70%+ correction rate)
+- Amnesia Test for context efficiency (40-60% reduction)
+- Chaos Engineering for robustness (<30s MTTR)
+- Ablation studies (Semantic Purge, Differential Auditing)
+
+### Documentation
+- Comprehensive wiki with architectural deep dives
+- Three Failure Types guide
+- Adaptive Memory Hierarchy documentation
+- Data Contracts and Schemas reference
+- Contributing guidelines
+
+## [0.1.0] - 2025-12-01
+
+### Added
+- Initial release of Self-Correcting Agent Kernel
+- Basic failure detection and correction
+- Simple prompt patching mechanism
+- Memory hierarchy prototype (single-tier)
+- Legacy API (`agent_kernel` module)
+- Core data models with Pydantic
+- Basic telemetry and logging
+- Initial test suite (50+ tests)
+- Example scripts and demos
+
+### Core Components
+- `SelfCorrectingAgentKernel` main class
+- Basic triage for failure routing
+- Simple patch application without simulation
+- Redis cache integration
+- Vector DB placeholder
+
+### Documentation
+- Initial README with architecture overview
+- Basic installation instructions
+- Quick-start examples
+- License and contribution guidelines
+
+---
+
+## Version History Summary
+
+- **v1.1.0** (2026-01-18): Production-ready with LLM integrations, multi-agent orchestration, security layer
+- **v1.0.0** (2026-01-15): Complete dual-loop architecture, all experiments validated
+- **v0.1.0** (2025-12-01): Initial prototype release
+
+---
+
+## Upgrade Guide
+
+### From 1.0.0 to 1.1.0
+
+**New Features:**
+- LLM clients now async: `await client.generate()`
+- Orchestrator for multi-agent workflows
+- GovernanceLayer for security screening
+- CLI tool: `scak --help`
+
+**Breaking Changes:**
+- None (backward compatible)
+
+**Recommended Actions:**
+1. Install optional dependencies: `pip install -e ".[llm]"`
+2. Update async code patterns to use new LLM clients
+3. Review security governance policies
+4. Try new CLI commands
+
+### From 0.1.0 to 1.0.0
+
+**New Architecture:**
+- Modern `src/` structure (recommended over legacy `agent_kernel/`)
+- Dual-loop replaces single-loop correction
+- Three-tier memory replaces single-tier cache
+
+**Breaking Changes:**
+- `src.kernel.triage.FixStrategy` enum values changed (SYNC_JIT, ASYNC_BATCH)
+- Memory controller API redesigned
+- Telemetry format changed to structured JSON
+
+**Migration Path:**
+1. Update imports: `from src.kernel.triage import FailureTriage`
+2. Replace memory calls with new MemoryController API
+3. Update telemetry to emit structured events
+4. Run tests to validate changes
+
+---
+
+## Deprecation Notices
+
+### Deprecated in 1.1.0
+- None
+
+### Deprecated in 1.0.0
+- Legacy `agent_kernel/` API (still supported, but use `src/` for new code)
+- Print-based logging (use structured telemetry instead)
+- Synchronous LLM calls (use async/await patterns)
+
+---
+
+## Release Notes
+
+### How to Cite
+
+```bibtex
+@software{scak2026,
+  title={Self-Correcting Agent Kernel: Automated Alignment via Differential Auditing and Semantic Memory Hygiene},
+  author={Self-Correcting Agent Team},
+  year={2026},
+  version={1.1.0},
+  url={https://github.com/imran-siddique/self-correcting-agent-kernel}
+}
+```
+
+### Links
+
+- **PyPI:** https://pypi.org/project/scak/
+- **GitHub:** https://github.com/imran-siddique/self-correcting-agent-kernel
+- **Documentation:** https://github.com/imran-siddique/self-correcting-agent-kernel/wiki
+- **Paper:** https://arxiv.org (to be published)
+
+---
+
+**Maintained by:** Self-Correcting Agent Team  
+**License:** MIT

modules/scak/CITATION.cff

@@ -0,0 +1,62 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "Self-Correcting Agent Kernel: Automated Alignment via Differential Auditing and Semantic Memory Hygiene"
+version: 1.1.0
+date-released: 2026-01-18
+authors:
+  - family-names: "Self-Correcting Agent Team"
+    name: "Self-Correcting Agent Team"
+repository-code: "https://github.com/imran-siddique/self-correcting-agent-kernel"
+url: "https://github.com/imran-siddique/self-correcting-agent-kernel"
+abstract: "A production-ready self-correcting agent kernel implementing dual-loop architecture (runtime safety + alignment engine) with differential auditing, semantic purge, and three-tier memory hierarchy. Novel contributions include Type A/B patch decay taxonomy, 5-10% audit overhead via give-up signal detection, and 40-60% context reduction on model upgrades."
+keywords:
+  - "AI agents"
+  - "self-correction"
+  - "alignment"
+  - "differential auditing"
+  - "semantic purge"
+  - "production ML"
+  - "agent reliability"
+  - "context management"
+license: MIT
+preferred-citation:
+  type: software
+  title: "Self-Correcting Agent Kernel: Automated Alignment via Differential Auditing and Semantic Memory Hygiene"
+  authors:
+    - family-names: "Self-Correcting Agent Team"
+      name: "Self-Correcting Agent Team"
+  year: 2026
+  url: "https://github.com/imran-siddique/self-correcting-agent-kernel"
+  notes: "Research foundations: Reflexion (NeurIPS 2023), Constitutional AI (Anthropic 2022), Voyager (arXiv:2305.16291)"
+references:
+  - type: article
+    title: "Reflexion: Language Agents with Verbal Reinforcement Learning"
+    authors:
+      - family-names: Shinn
+        given-names: Noah
+      - family-names: Cassano
+        given-names: Federico
+      - family-names: Gopinath
+        given-names: Ashwin
+      - family-names: Narasimhan
+        given-names: Karthik
+      - family-names: Yao
+        given-names: Shunyu
+    year: 2023
+    conference: "NeurIPS 2023"
+    url: "https://arxiv.org/abs/2303.11366"
+  - type: article
+    title: "Constitutional AI: Harmlessness from AI Feedback"
+    authors:
+      - family-names: Bai
+        given-names: Yuntao
+    year: 2022
+    publisher: "Anthropic"
+    url: "https://arxiv.org/abs/2212.08073"
+  - type: article
+    title: "Voyager: An Open-Ended Embodied Agent with Large Language Models"
+    authors:
+      - family-names: Wang
+        given-names: Guanzhi
+    year: 2023
+    url: "https://arxiv.org/abs/2305.16291"

modules/scak/CONTRIBUTING.md

@@ -0,0 +1,429 @@
+# Contributing to Self-Correcting Agent Kernel
+
+Thank you for your interest in contributing to the Self-Correcting Agent Kernel (SCAK)! This document provides guidelines for contributions.
+
+## Table of Contents
+
+1. [Code of Conduct](#code-of-conduct)
+2. [Getting Started](#getting-started)
+3. [Development Setup](#development-setup)
+4. [Coding Standards](#coding-standards)
+5. [Testing](#testing)
+6. [Pull Request Process](#pull-request-process)
+7. [Research Contributions](#research-contributions)
+8. [Documentation](#documentation)
+
+---
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive environment. Please:
+
+- ✅ Be respectful and considerate
+- ✅ Focus on constructive feedback
+- ✅ Welcome newcomers and help them learn
+- ❌ No harassment, discrimination, or trolling
+
+---
+
+## Getting Started
+
+### Types of Contributions
+
+We welcome:
+
+1. **Bug Fixes**: Fix existing issues in the codebase
+2. **Feature Enhancements**: Improve existing features
+3. **New Features**: Add new capabilities (discuss first in an issue)
+4. **Documentation**: Improve README, wiki, or code comments
+5. **Tests**: Add or improve test coverage
+6. **Research**: Add benchmarks, datasets, or experiments
+7. **Performance**: Optimize latency or resource usage
+
+### Before You Start
+
+1. **Check existing issues**: Look for related issues or PRs
+2. **Open a discussion**: For large changes, create an issue first
+3. **Read the architecture**: Understand the dual-loop design (see `wiki/`)
+4. **Review coding standards**: See below
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.8+ (recommended: 3.10)
+- Git
+- Virtual environment tool (venv, conda, etc.)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/imran-siddique/self-correcting-agent-kernel.git
+cd self-correcting-agent-kernel
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e ".[dev]"  # Includes testing and development tools
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_triage.py -v
+
+# Run with coverage
+pytest tests/ --cov=src --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Run type checking (if mypy is installed)
+mypy src/
+
+# Run linting (if flake8 is installed)
+flake8 src/ --max-line-length=120
+```
+
+---
+
+## Coding Standards
+
+We follow **Partner-level coding standards** (see `.github/copilot-instructions.md`).
+
+### Key Principles
+
+1. **Type Safety**: All functions must have type hints
+   ```python
+   def compute_score(value: float, threshold: float = 0.5) -> bool:
+       return value >= threshold
+   ```
+
+2. **Async-First**: All I/O operations must be async
+   ```python
+   async def call_llm(prompt: str) -> str:
+       return await llm_client.generate(prompt)
+   ```
+
+3. **No Silent Failures**: Every `try/except` must emit telemetry
+   ```python
+   try:
+       result = risky_operation()
+   except Exception as e:
+       telemetry.emit_failure_detected(
+           agent_id=agent_id,
+           error_message=str(e)
+       )
+       raise
+   ```
+
+4. **Pydantic Models**: Use Pydantic for data exchange
+   ```python
+   from pydantic import BaseModel
+   
+   class PatchRequest(BaseModel):
+       agent_id: str
+       patch_content: str
+       patch_type: str
+   ```
+
+5. **Structured Telemetry**: JSON logs, not print statements
+   ```python
+   telemetry.emit_patch_applied(
+       agent_id=agent_id,
+       patch_id=patch.patch_id
+   )
+   ```
+
+### File Organization
+
+- **src/kernel/**: Core correction engine
+- **src/agents/**: Agent implementations
+- **src/interfaces/**: External interfaces (telemetry, LLM clients, etc.)
+- **tests/**: Test suite
+- **experiments/**: Benchmarks and validation
+- **examples/**: Demos and usage examples
+
+### Naming Conventions
+
+- **Functions**: `snake_case` (e.g., `handle_failure`, `compute_score`)
+- **Classes**: `PascalCase` (e.g., `ShadowTeacher`, `MemoryController`)
+- **Constants**: `UPPER_SNAKE_CASE` (e.g., `GLOBAL_SEED`, `MAX_RETRIES`)
+- **Modules**: `snake_case` (e.g., `triage.py`, `memory.py`)
+
+---
+
+## Testing
+
+### Test Requirements
+
+Every PR must include:
+
+1. **Unit tests** for new functions
+2. **Integration tests** for new features
+3. **Docstrings** explaining test purpose
+4. **Assertions** with clear failure messages
+
+### Example Test
+
+```python
+import pytest
+from src.kernel.triage import FailureTriage, FixStrategy
+
+
+class TestFailureTriage:
+    """Test the Failure Triage Engine."""
+    
+    @pytest.fixture
+    def triage(self):
+        """Create triage instance."""
+        return FailureTriage()
+    
+    def test_critical_operations_go_sync(self, triage):
+        """Test that critical operations route to SYNC_JIT."""
+        strategy = triage.decide_strategy(
+            user_prompt="Process refund for customer",
+            context={"action": "execute_payment"}
+        )
+        
+        assert strategy == FixStrategy.SYNC_JIT, \
+            "Payment operations must be sync for safety"
+```
+
+### Running Tests Locally
+
+```bash
+# Before submitting PR, run:
+pytest tests/ -v --cov=src
+```
+
+Expected: All tests pass, >80% coverage
+
+---
+
+## Pull Request Process
+
+### 1. Fork and Branch
+
+```bash
+# Fork the repository on GitHub, then:
+git clone https://github.com/YOUR_USERNAME/self-correcting-agent-kernel.git
+cd self-correcting-agent-kernel
+
+# Create feature branch
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Changes
+
+- Follow coding standards (see above)
+- Write tests
+- Update documentation
+- Add yourself to `.github/CONTRIBUTORS.md` (if it exists)
+
+### 3. Commit
+
+**Commit Message Format:**
+```
+<type>: <description>
+
+<optional body>
+
+<optional footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `test`: Adding or updating tests
+- `refactor`: Code restructuring (no behavior change)
+- `perf`: Performance improvement
+- `chore`: Maintenance (dependencies, config, etc.)
+
+**Example:**
+```bash
+git add .
+git commit -m "feat: add multi-turn laziness detection
+
+- Extend Completeness Auditor to handle multi-turn context
+- Add new test suite for multi-turn scenarios
+- Update GAIA benchmark with multi-turn queries
+
+Closes #123"
+```
+
+### 4. Push and Open PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then open a pull request on GitHub with:
+
+- **Title**: Clear, concise summary
+- **Description**: What changes, why, and how to test
+- **Linked Issues**: `Closes #123` or `Relates to #456`
+- **Checklist**: 
+  - [ ] Tests pass
+  - [ ] Documentation updated
+  - [ ] Coding standards followed
+
+### 5. Code Review
+
+- Respond to feedback promptly
+- Make requested changes
+- Push updates to the same branch (PR auto-updates)
+
+### 6. Merge
+
+Once approved by maintainers:
+- PR will be squashed and merged
+- Feature branch can be deleted
+
+---
+
+## Research Contributions
+
+### Adding Benchmarks
+
+To add a new benchmark:
+
+1. **Create dataset**: Add to `datasets/<benchmark_name>/`
+   ```json
+   {
+     "id": "query_001",
+     "category": "laziness",
+     "query": "Find recent errors",
+     "ground_truth": {"data_exists": true, ...}
+   }
+   ```
+
+2. **Create benchmark script**: Add to `experiments/<benchmark_name>/`
+   ```python
+   def run_benchmark(queries: List[Dict]) -> Dict:
+       # Implementation
+       pass
+   ```
+
+3. **Document**: Add README.md explaining:
+   - Purpose of benchmark
+   - How to run
+   - Expected results
+   - Citation (if based on prior work)
+
+4. **Cite prior work**: Add references to `RESEARCH.md`
+
+### Adding Papers to Bibliography
+
+To add a new paper citation:
+
+1. **Add to RESEARCH.md**: In relevant section, add:
+   ```markdown
+   ### [Section Name]
+   
+   1. **Authors (Year).**  
+      *"Paper Title"*  
+      Venue. DOI/arXiv
+      - **Core Contribution**: What they did
+      - **Our Implementation**: How we use it
+      - **Connection**: Why it's relevant
+   ```
+
+2. **Add to paper/bibliography.bib** (for LaTeX):
+   ```bibtex
+   @inproceedings{author2023title,
+     title={Paper Title},
+     author={Author, A. and Author, B.},
+     booktitle={Venue},
+     year={2023},
+     url={https://arxiv.org/abs/...}
+   }
+   ```
+
+---
+
+## Documentation
+
+### Code Documentation
+
+**Docstrings** (Google style):
+```python
+def handle_failure(
+    agent_id: str,
+    error_message: str,
+    context: dict
+) -> dict:
+    """
+    Handle agent failure with Dual-Loop Architecture.
+    
+    Args:
+        agent_id: Unique agent identifier
+        error_message: Error description
+        context: Additional context (tool trace, user prompt, etc.)
+    
+    Returns:
+        Dict with patch_applied, patch_id, strategy
+    
+    Raises:
+        ValueError: If agent_id is invalid
+    
+    Example:
+        >>> result = handle_failure("agent-001", "Timeout", {})
+        >>> print(result["patch_applied"])
+        True
+    """
+    # Implementation
+    pass
+```
+
+### README Updates
+
+If your change affects usage:
+
+1. Update relevant section in `README.md`
+2. Add example if new feature
+3. Update table of contents if new section
+
+### Wiki Updates
+
+For architectural changes:
+
+1. Update relevant wiki page (`wiki/*.md`)
+2. Add diagrams if helpful (Mermaid or ASCII)
+3. Link from main wiki README
+
+---
+
+## Questions?
+
+- **Issues**: Open a GitHub issue for bugs or questions
+- **Discussions**: Use GitHub Discussions for general questions
+- **Email**: research@scak.ai (for sensitive or private matters)
+
+---
+
+## Recognition
+
+Contributors will be:
+
+- Listed in `.github/CONTRIBUTORS.md`
+- Acknowledged in paper (if research contribution)
+- Invited to co-author follow-up papers (for significant contributions)
+
+---
+
+Thank you for contributing to SCAK! 🚀
+
+**Last Updated:** 2026-01-18  
+**Version:** 1.0

modules/scak/Dockerfile

@@ -0,0 +1,58 @@
+# Dockerfile for Self-Correcting Agent Kernel
+#
+# Multi-stage build for production deployment
+# Based on official Python slim image
+
+FROM python:3.11-slim as base
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better layer caching
+COPY requirements.txt .
+COPY setup.py .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir -e .
+
+# Development stage
+FROM base as development
+
+# Install development dependencies
+RUN pip install --no-cache-dir pytest pytest-asyncio jupyter streamlit
+
+# Copy source code
+COPY . .
+
+# Expose ports
+EXPOSE 8501
+
+# Default command for development
+CMD ["streamlit", "run", "dashboard.py"]
+
+# Production stage
+FROM base as production
+
+# Copy only necessary files
+COPY src/ ./src/
+COPY agent_kernel/ ./agent_kernel/
+COPY cli.py .
+
+# Create non-root user
+RUN useradd -m -u 1000 scak && chown -R scak:scak /app
+USER scak
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import sys; sys.exit(0)"
+
+# Default command
+ENTRYPOINT ["python", "cli.py"]
+CMD ["--help"]