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

modules/caas/benchmarks/data/sample_corpus/auth_module.py

@@ -0,0 +1,211 @@
+"""
+User Authentication Module
+
+This module provides secure user authentication functionality including
+password hashing, token generation, and session management.
+"""
+
+import hashlib
+import secrets
+import time
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails."""
+    pass
+
+
+class User:
+    """
+    Represents a user in the system.
+    
+    Attributes:
+        username: Unique username
+        email: User's email address
+        created_at: Account creation timestamp
+    """
+    
+    def __init__(self, username: str, email: str, password_hash: str):
+        self.username = username
+        self.email = email
+        self.password_hash = password_hash
+        self.created_at = datetime.now()
+        self.last_login: Optional[datetime] = None
+        self.failed_attempts = 0
+        self.is_locked = False
+    
+    def check_password(self, password: str) -> bool:
+        """
+        Verify password against stored hash.
+        
+        Args:
+            password: Plain text password to check
+            
+        Returns:
+            True if password matches, False otherwise
+        """
+        password_hash = hashlib.sha256(password.encode()).hexdigest()
+        return secrets.compare_digest(password_hash, self.password_hash)
+    
+    def update_last_login(self):
+        """Update last login timestamp."""
+        self.last_login = datetime.now()
+        self.failed_attempts = 0
+    
+    def increment_failed_attempts(self):
+        """Track failed login attempts and lock account if necessary."""
+        self.failed_attempts += 1
+        if self.failed_attempts >= 5:
+            self.is_locked = True
+
+
+class AuthenticationManager:
+    """
+    Manages user authentication and session tokens.
+    
+    This class handles:
+    - User login/logout
+    - Token generation and validation
+    - Session management
+    - Account lockout policies
+    """
+    
+    def __init__(self, token_expiry_hours: int = 24):
+        self.users: Dict[str, User] = {}
+        self.sessions: Dict[str, Dict[str, Any]] = {}
+        self.token_expiry_hours = token_expiry_hours
+    
+    def register_user(self, username: str, email: str, password: str) -> User:
+        """
+        Register a new user.
+        
+        Args:
+            username: Desired username
+            email: User's email address
+            password: Plain text password (will be hashed)
+            
+        Returns:
+            Newly created User object
+            
+        Raises:
+            ValueError: If username already exists
+        """
+        if username in self.users:
+            raise ValueError(f"Username '{username}' already exists")
+        
+        password_hash = hashlib.sha256(password.encode()).hexdigest()
+        user = User(username, email, password_hash)
+        self.users[username] = user
+        return user
+    
+    def authenticate(self, username: str, password: str) -> str:
+        """
+        Authenticate user and create session.
+        
+        Args:
+            username: Username to authenticate
+            password: Password to verify
+            
+        Returns:
+            Session token string
+            
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        user = self.users.get(username)
+        
+        if user is None:
+            raise AuthenticationError("Invalid username or password")
+        
+        if user.is_locked:
+            raise AuthenticationError("Account is locked due to too many failed attempts")
+        
+        if not user.check_password(password):
+            user.increment_failed_attempts()
+            raise AuthenticationError("Invalid username or password")
+        
+        # Generate session token
+        token = secrets.token_urlsafe(32)
+        expiry = datetime.now() + timedelta(hours=self.token_expiry_hours)
+        
+        self.sessions[token] = {
+            "username": username,
+            "expiry": expiry,
+            "created_at": datetime.now()
+        }
+        
+        user.update_last_login()
+        return token
+    
+    def validate_token(self, token: str) -> Optional[str]:
+        """
+        Validate session token.
+        
+        Args:
+            token: Session token to validate
+            
+        Returns:
+            Username if token is valid, None otherwise
+        """
+        session = self.sessions.get(token)
+        
+        if session is None:
+            return None
+        
+        if datetime.now() > session["expiry"]:
+            # Token expired, remove from sessions
+            del self.sessions[token]
+            return None
+        
+        return session["username"]
+    
+    def logout(self, token: str):
+        """
+        End user session.
+        
+        Args:
+            token: Session token to invalidate
+        """
+        if token in self.sessions:
+            del self.sessions[token]
+    
+    def cleanup_expired_sessions(self):
+        """Remove all expired session tokens."""
+        now = datetime.now()
+        expired_tokens = [
+            token for token, session in self.sessions.items()
+            if now > session["expiry"]
+        ]
+        for token in expired_tokens:
+            del self.sessions[token]
+
+
+# Example usage
+if __name__ == "__main__":
+    # Initialize authentication manager
+    auth_manager = AuthenticationManager(token_expiry_hours=12)
+    
+    # Register a new user
+    user = auth_manager.register_user(
+        username="john_doe",
+        email="john@example.com",
+        password="SecurePassword123!"
+    )
+    print(f"Registered user: {user.username}")
+    
+    # Authenticate user
+    try:
+        token = auth_manager.authenticate("john_doe", "SecurePassword123!")
+        print(f"Login successful! Token: {token[:16]}...")
+        
+        # Validate token
+        username = auth_manager.validate_token(token)
+        print(f"Token valid for user: {username}")
+        
+        # Logout
+        auth_manager.logout(token)
+        print("User logged out")
+    except AuthenticationError as e:
+        print(f"Authentication failed: {e}")

modules/caas/benchmarks/data/sample_corpus/contribution_guide.md

@@ -0,0 +1,185 @@
+# Software Development Contribution Guide
+
+## Getting Started
+
+Welcome to our project! This guide will help you start contributing.
+
+### Prerequisites
+
+- Python 3.8 or higher
+- Git version control
+- A GitHub account
+
+### Setting Up Your Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/company/project.git
+cd project
+
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+Always create a new branch for your work:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+Branch naming conventions:
+- `feature/` for new features
+- `bugfix/` for bug fixes
+- `docs/` for documentation updates
+- `refactor/` for code refactoring
+
+### 2. Make Your Changes
+
+- Write clear, concise commit messages
+- Follow the coding style guide (see STYLE_GUIDE.md)
+- Add tests for new functionality
+- Update documentation as needed
+
+### 3. Test Your Changes
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Run linting
+black src/ tests/
+ruff check src/ tests/
+
+# Check type hints
+mypy src/
+```
+
+### 4. Submit a Pull Request
+
+1. Push your branch to GitHub
+2. Open a pull request against the `main` branch
+3. Fill out the PR template completely
+4. Request reviews from appropriate team members
+5. Address feedback and update your PR
+
+## Code Review Process
+
+### Review Guidelines
+
+- All PRs require at least 2 approvals
+- CI checks must pass before merging
+- Reviews should be completed within 2 business days
+- Be constructive and respectful in feedback
+
+### What Reviewers Look For
+
+- Code correctness and functionality
+- Test coverage (minimum 80%)
+- Documentation completeness
+- Code style consistency
+- Security considerations
+- Performance implications
+
+## Testing
+
+### Unit Tests
+
+Write unit tests for all new functions and classes:
+
+```python
+def test_user_authentication():
+    user = User(username="test", password="secure123")
+    assert user.is_authenticated() == True
+```
+
+### Integration Tests
+
+Test interactions between components:
+
+```python
+def test_api_endpoint():
+    response = client.get("/api/users")
+    assert response.status_code == 200
+```
+
+### Test Coverage
+
+Maintain minimum 80% code coverage:
+
+```bash
+pytest --cov=src --cov-report=html
+```
+
+## Documentation
+
+### Code Documentation
+
+Use docstrings for all public functions and classes:
+
+```python
+def calculate_discount(price: float, discount_percent: float) -> float:
+    """
+    Calculate the discounted price.
+    
+    Args:
+        price: Original price
+        discount_percent: Discount percentage (0-100)
+        
+    Returns:
+        Discounted price
+        
+    Raises:
+        ValueError: If discount_percent is not in valid range
+    """
+    if not 0 <= discount_percent <= 100:
+        raise ValueError("Discount must be between 0 and 100")
+    return price * (1 - discount_percent / 100)
+```
+
+### README Updates
+
+Update the README when adding:
+- New features
+- Configuration options
+- Installation requirements
+- Usage examples
+
+## Release Process
+
+### Version Numbers
+
+We follow Semantic Versioning (MAJOR.MINOR.PATCH):
+- MAJOR: Breaking changes
+- MINOR: New features (backwards compatible)
+- PATCH: Bug fixes
+
+### Creating a Release
+
+1. Update version in `__init__.py`
+2. Update CHANGELOG.md
+3. Create a git tag: `git tag v1.2.3`
+4. Push tag: `git push origin v1.2.3`
+5. GitHub Actions will automatically build and publish
+
+## Getting Help
+
+- Slack: #dev-team channel
+- Email: dev-team@company.com
+- Office Hours: Tuesdays 2-3 PM EST
+
+## Code of Conduct
+
+Please read and follow our CODE_OF_CONDUCT.md. We are committed to providing a welcoming and inclusive environment for all contributors.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

modules/caas/benchmarks/data/sample_corpus/remote_work_policy.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Company Policy: Remote Work Guidelines</title>
+</head>
+<body>
+    <h1>Remote Work Policy</h1>
+    <p><strong>Effective Date:</strong> January 1, 2025</p>
+    <p><strong>Last Updated:</strong> January 15, 2026</p>
+    
+    <h2>1. Overview</h2>
+    <p>This policy establishes guidelines for employees working remotely. It applies to all full-time and part-time employees who have been approved for remote work arrangements.</p>
+    
+    <h2>2. Eligibility</h2>
+    <ul>
+        <li>Must have been with the company for at least 6 months</li>
+        <li>Must have a suitable home office setup</li>
+        <li>Must have reliable high-speed internet (minimum 50 Mbps)</li>
+        <li>Role must be compatible with remote work</li>
+    </ul>
+    
+    <h2>3. Working Hours</h2>
+    <p>Remote employees are expected to maintain standard working hours (9 AM - 5 PM local time) unless alternative arrangements have been approved by their manager. Core hours for meetings are 10 AM - 3 PM EST.</p>
+    
+    <h2>4. Equipment and Technology</h2>
+    <ul>
+        <li>Company-provided laptop and accessories</li>
+        <li>VPN access required for all company resources</li>
+        <li>Security software must be kept up to date</li>
+        <li>Personal devices must not be used for company work</li>
+    </ul>
+    
+    <h2>5. Communication Requirements</h2>
+    <p>Remote employees must:</p>
+    <ul>
+        <li>Respond to Slack messages within 1 hour during working hours</li>
+        <li>Attend all required team meetings via video conference</li>
+        <li>Keep camera on during meetings</li>
+        <li>Update status in Slack when away from desk</li>
+    </ul>
+    
+    <h2>6. Security and Confidentiality</h2>
+    <p>All employees must comply with the company's information security policy. This includes:</p>
+    <ul>
+        <li>Using encrypted connections for all company data</li>
+        <li>Not discussing confidential matters in public spaces</li>
+        <li>Securing physical workspace when not present</li>
+        <li>Immediately reporting any security incidents</li>
+    </ul>
+    
+    <h2>7. Performance Expectations</h2>
+    <p>Remote employees are held to the same performance standards as office-based employees. Regular check-ins with managers are required (minimum weekly).</p>
+    
+    <h2>8. Termination of Remote Work Arrangement</h2>
+    <p>The company reserves the right to terminate remote work arrangements with 30 days notice if performance expectations are not met or business needs change.</p>
+</body>
+</html>

modules/caas/benchmarks/hf_dataset/README.md

@@ -0,0 +1,214 @@
+---
+annotations_creators:
+- expert-generated
+language:
+- en
+language_creators:
+- expert-generated
+license:
+- mit
+multilinguality:
+- monolingual
+pretty_name: CaaS Benchmark Corpus
+size_categories:
+- n<1K
+source_datasets:
+- original
+tags:
+- context-extraction
+- rag
+- document-processing
+- enterprise-ai
+- benchmarking
+task_categories:
+- text-retrieval
+- question-answering
+task_ids:
+- document-retrieval
+---
+
+# CaaS Benchmark Corpus v1
+
+A diverse collection of synthetic enterprise documents for benchmarking context extraction and RAG systems.
+
+## Dataset Description
+
+This dataset contains **16 representative enterprise documents** spanning multiple formats and domains, designed to evaluate:
+
+- **Structure-aware indexing** - Can the system identify high-value vs. low-value content?
+- **Time decay relevance** - Does the system properly weight recent vs. old information?
+- **Pragmatic truth detection** - Can the system identify conflicts between official and informal sources?
+- **Cross-document reasoning** - Can the system synthesize information across documents?
+
+### Supported Tasks
+
+- Document retrieval and ranking
+- Question answering over enterprise documents
+- Context extraction for LLM augmentation
+- Information extraction benchmarking
+
+### Languages
+
+English (en)
+
+## Dataset Structure
+
+### Data Files
+
+| File | Type | Domain | Description |
+|------|------|--------|-------------|
+| `auth_module.py` | Python | Engineering | Authentication module with security features |
+| `data_processor.py` | Python | Engineering | Data processing pipeline with validation |
+| `api_reference.md` | Markdown | Documentation | REST API reference with examples |
+| `contribution_guide.md` | Markdown | Documentation | Developer contribution guidelines |
+| `troubleshooting_guide.md` | Markdown | Documentation | Common issues and solutions |
+| `employee_handbook.md` | Markdown | HR/Policy | Employee policies and benefits |
+| `privacy_policy.md` | Markdown | Legal | Data privacy and compliance |
+| `software_license_agreement.md` | Markdown | Legal | Software licensing terms |
+| `incident_report.md` | Markdown | Security | Security incident documentation |
+| `meeting_notes.md` | Markdown | Business | Engineering team meeting notes |
+| `onboarding_checklist.md` | Markdown | HR | New employee onboarding tasks |
+| `release_notes.md` | Markdown | Engineering | Software release documentation |
+| `config_example.yaml` | YAML | Engineering | Configuration file example |
+| `database_schema.sql` | SQL | Engineering | Database schema definitions |
+| `remote_work_policy.html` | HTML | HR/Policy | Remote work guidelines |
+| `README.md` | Markdown | Documentation | Sample corpus overview |
+
+### Document Characteristics
+
+| Characteristic | Range |
+|---------------|-------|
+| Document length | 50 - 500 lines |
+| Token count | 500 - 5,000 tokens |
+| Formats | Python, Markdown, HTML, SQL, YAML |
+| Domains | Engineering, Legal, HR, Security, Business |
+
+### Data Fields
+
+Each document contains:
+
+- **Content**: The full text of the document
+- **Filename**: Original filename with extension
+- **File type**: Document format (py, md, html, sql, yaml)
+- **Domain**: Business domain classification
+- **Structure**: Hierarchical sections (where applicable)
+- **Timestamps**: Simulated creation/update dates
+
+## Dataset Creation
+
+### Curation Rationale
+
+Enterprise AI systems must handle diverse document types with varying structures, importance levels, and freshness requirements. This corpus was designed to:
+
+1. **Represent real enterprise diversity** - Mix of technical, legal, HR, and operational documents
+2. **Include temporal signals** - Documents have explicit dates for time-decay testing
+3. **Provide ground truth** - Known structure and content for evaluation
+4. **Enable ablation studies** - Test individual CaaS features in isolation
+
+### Source Data
+
+All documents are **synthetic**, created specifically for this benchmark. They are realistic representations of enterprise documents but contain no real company data, PII, or copyrighted content.
+
+### Annotations
+
+Documents include:
+
+- **Section hierarchy** - Explicit heading structure
+- **Content classification** - Domain and document type labels
+- **Temporal metadata** - Creation and update timestamps
+- **Cross-references** - Links between related documents (e.g., incident report references meeting notes)
+
+## Considerations for Using the Data
+
+### Social Impact
+
+This dataset is designed for benchmarking AI systems. The synthetic documents represent common enterprise scenarios but do not reflect any real organization's data.
+
+### Biases
+
+- Documents reflect Western/US business practices
+- English language only
+- Tech company context (software, SaaS)
+
+### Limitations
+
+- Small corpus size (16 documents)
+- Limited to text content (no images, tables as images)
+- Synthetic content may not capture all real-world complexity
+
+## Additional Information
+
+### Dataset Curators
+
+Context-as-a-Service Team
+
+### Licensing Information
+
+MIT License
+
+### Citation Information
+
+```bibtex
+@dataset{caas_benchmark_corpus_2026,
+  author = {Context-as-a-Service Team},
+  title = {CaaS Benchmark Corpus: A Diverse Enterprise Document Collection for RAG Evaluation},
+  year = {2026},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/datasets/mosiddi/caas-benchmark-corpus-v1}
+}
+```
+
+### Contributions
+
+To contribute additional documents or improvements:
+
+1. Fork the [CaaS repository](https://github.com/imran-siddique/context-as-a-service)
+2. Add documents to `benchmarks/data/sample_corpus/`
+3. Submit a pull request
+
+## Usage
+
+### Loading the Dataset
+
+```python
+from datasets import load_dataset
+
+# Load from Hugging Face
+dataset = load_dataset("mosiddi/caas-benchmark-corpus-v1")
+
+# Or load locally
+from pathlib import Path
+corpus_path = Path("benchmarks/data/sample_corpus")
+documents = list(corpus_path.glob("*"))
+```
+
+### Running Benchmarks
+
+```bash
+# Clone the CaaS repository
+git clone https://github.com/imran-siddique/context-as-a-service.git
+cd context-as-a-service
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run benchmarks
+python benchmarks/run_evaluation.py --corpus benchmarks/data/sample_corpus/
+```
+
+### Example: Evaluate Structure-Aware Indexing
+
+```python
+from caas import DocumentProcessor
+from benchmarks.metrics import evaluate_structure_detection
+
+processor = DocumentProcessor()
+results = []
+
+for doc_path in corpus_path.glob("*.md"):
+    doc = processor.process(doc_path)
+    accuracy = evaluate_structure_detection(doc, ground_truth[doc_path.name])
+    results.append(accuracy)
+
+print(f"Structure detection accuracy: {sum(results)/len(results):.2%}")
+```