CyberScribe v3 - OOP Refactoring Complete ✅

Cybersecurity session tracker with comprehensive OOP architecture, multi-agent system, and AI-powered analysis.

Status: Phase 1-6 Complete | 167/167 Tests Passing | 0.70s Execution | Production Ready ✅

6-Phase Architecture Overview

┌────────────────────────────────────────────────────────────┐
│              CyberScribe v3 - OOP Architecture             │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  Phase 1: CORE FOUNDATION (31 tests)                     │
│  ├─ Models: 7 dataclasses + 3 enums (type-safe)          │
│  ├─ Contracts: 10 abstract base classes (27 methods)     │
│  ├─ SessionManager: Dependency injection orchestration   │
│  └─ Config & Logging: Centralized setup                  │
│                                                            │
│  Phase 2: CAPTURE SYSTEM (28 tests)                      │
│  ├─ ScreenshotCapture: OCR-based activity detection      │
│  ├─ SmartScreenshotCapture: Optimized frame intervals    │
│  ├─ KeystrokeCapture: Event-driven typing detection      │
│  ├─ URLCapture: Browser URL tracking                     │
│  ├─ ActivityDetector: 7-state machine                    │
│  ├─ ErrorDetector: 8 pattern detection                   │
│  ├─ FrustrationDetector: Behavioral analysis             │
│  └─ HybridCapture: Orchestrator (200 lines)              │
│                                                            │
│  Phase 3: LLM PROVIDERS (27 tests)                       │
│  ├─ OllamaProvider: Local model support                  │
│  ├─ OpenAIProvider: GPT-4/gpt-4o cloud API               │
│  ├─ AnthropicProvider: Claude models                     │
│  ├─ GeminiProvider: Google Gemini API                    │
│  ├─ LiteLLMProvider: 100+ model proxy                    │
│  ├─ ProviderFactory: Registration & caching              │
│  └─ RetryLogic: @retry_with_backoff decorator            │
│                                                            │
│  Phase 4: STORAGE LAYER (25 tests)                       │
│  ├─ SessionRepository: JSON persistence                  │
│  ├─ AnalysisRepository: JSON + Markdown reports          │
│  ├─ Date-based filtering & querying                      │
│  └─ Serialization/deserialization utilities              │
│                                                            │
│  Phase 5: AGENT SYSTEM (33 tests)                        │
│  ├─ DocumentationAgent: Markdown report generation       │
│  ├─ AnalysisAgent: Productivity metrics & trends         │
│  └─ Focus score calculation (4-tier system)              │
│                                                            │
│  Phase 6: INTEGRATION & TESTING (23 tests)               │
│  ├─ AgentCoordinator: Multi-agent orchestration          │
│  ├─ End-to-end workflows: Session → Processing → Store   │
│  ├─ Error handling & resilience testing                  │
│  └─ Scalability validation (500+ activities)             │
│                                                            │
└────────────────────────────────────────────────────────────┘

Key Features ✨

🎯 Type-Safe Architecture

Dataclasses: All models use Python 3.10+ dataclasses with type hints
Abstract Contracts: 10 base classes define behavior contracts
Dependency Injection: Components receive dependencies via constructors
Factory Patterns: Extensible provider and agent creation

📊 Session Tracking

Hybrid Capture: 8 capture implementations with automatic selection
Activity Categorization: Learning, Distraction, Terminal, Tool, Neutral
State Machines: 7-state activity tracking (IDLE, TYPING, READING, etc.)
OCR Integration: Tesseract-based window content analysis

🤖 Multi-Agent System

DocumentationAgent: Generates markdown reports with statistics
AnalysisAgent: Productivity analysis with trend detection
AgentCoordinator: Orchestrates multi-agent workflows

🧠 LLM Support

5 Providers: Ollama, OpenAI, Anthropic, Gemini, LiteLLM
Provider Factory: Extensible registration system
Retry Logic: Exponential backoff with configurable limits
Cloud & Local: Support for both cloud APIs and local models

💾 Data Persistence

SessionRepository: JSON-based session storage
AnalysisRepository: JSON + Markdown report storage
Date Filtering: Query sessions by date range
Serialization: Automatic model-to-dict conversion

⚡ Performance & Reliability

Fast Tests: 167 tests pass in 0.7 seconds
Scalability: Handles 500+ activities per session
Error Recovery: Graceful degradation on component failures
Batch Processing: Efficient multi-session workflows

Quick Start

Prerequisites

Python 3.11.9
Virtual environment
pytest 9.0.3+

Installation

cd c:\Users\gowth\Documents\Project\cyber-scribe
python -m venv venv
.\venv\Scripts\activate
pip install -e .
pip install pytest pytest-mock pytest-cov

Run Tests

# All tests (167 total)
python -m pytest tests/unit/ -v

# By phase
python -m pytest tests/unit/test_agents/ -v          # Phase 5
python -m pytest tests/unit/test_storage/ -v         # Phase 4
python -m pytest tests/unit/test_llm/ -v             # Phase 3
python -m pytest tests/unit/test_capture/ -v         # Phase 2
python -m pytest tests/unit/test_core/ -v            # Phase 1
python -m pytest tests/unit/test_integration/ -v     # Phase 6

Project Structure

src/cyberscribe/
├── models.py                    # 7 dataclasses + 3 enums
├── config/
│   └── __init__.py             # Configuration management
├── core/
│   ├── base.py                 # 10 abstract base classes
│   ├── session.py              # SessionManager orchestrator
│   └── logger.py               # Logging setup
├── capture/
│   ├── screenshot.py           # Screenshot + Smart variant
│   ├── keystroke.py            # Keystroke logging
│   ├── url.py                  # URL tracking
│   ├── activity.py             # Activity state machine
│   ├── error.py                # Error detection
│   ├── frustration.py          # Frustration detection
│   ├── hybrid.py               # HybridCapture orchestrator
│   └── __init__.py
├── llm/
│   ├── base.py                 # (in core/base.py)
│   ├── ollama.py               # Ollama provider
│   ├── openai.py               # OpenAI provider
│   ├── anthropic.py            # Anthropic provider
│   ├── gemini.py               # Gemini provider
│   ├── litellm.py              # LiteLLM provider
│   ├── factory.py              # ProviderFactory
│   ├── __init__.py
│   └── retry_logic.py          # Retry decorator
├── storage/
│   ├── session_repository.py   # Session persistence
│   ├── analysis_repository.py  # Analysis/report storage
│   └── __init__.py
├── agents/
│   ├── documentation_agent.py  # Report generation
│   ├── analysis_agent.py       # Analytics & insights
│   ├── agent_coordinator.py    # Multi-agent orchestrator
│   └── __init__.py
└── utils/
    └── logger.py               # Logging utilities

tests/unit/
├── test_capture/               # Phase 2: 28 tests
├── test_core/                  # Phase 1: 31 tests
├── test_llm/                   # Phase 3: 27 tests
├── test_storage/               # Phase 4: 25 tests
├── test_agents/                # Phase 5: 33 tests
└── test_integration/           # Phase 6: 23 tests

Features

Activity Tracking

5 Categories: Learning, Terminal, Tool, Distraction, Neutral
YouTube Intent Detection: Educational vs entertainment content
Quick Notes: Real-time manual notes via quicklog.txt
Focus Score: 1-10 productivity metric

Hybrid Capture

Base screenshots every 10 seconds (all scenarios)
Keystroke logging in terminal/IDE windows only
URL tracking in browser windows
Activity state machine tracking
Error message detection in OCR
Frustration detection (rapid category switching)

LLM Processing

Local-first: Ollama with Gemma2 models
Model routing: 2B model for chunks, 9B for synthesis
Parallel processing: Multi-threaded chunk processing
Cloud support: OpenAI, Anthropic, Gemini (with data redaction)
Factual extraction: Strict category-separated prompts prevent hallucination

Distraction Analysis

Classifies 6 trigger types:

Trigger Type	Detection
`entertainment_escape`	YouTube, Netflix switches
`social_interaction`	Discord, Slack switches
`social_media_browsing`	Reddit, Twitter, Facebook
`mindless_switch`	Random unplanned switches
`distraction_chain`	Switching between distracting apps
`idle_distraction`	No prior activity before distraction

Detects 3 behavior patterns:

Pattern	Threshold	Meaning
`mindless_browsing`	>50% mindless switches	Habitual/impulse behavior
`distraction_cascade`	>30% chain distractions	Hard to break free once distracted
`triggered_distraction`	Otherwise	Clear trigger-based distractions

Configuration

Core Settings (`config.py`)

Setting	Default	Description
`CAPTURE_EVERY`	10	Screenshot interval (seconds)
`HYBRID_CAPTURE`	True	Enable enhanced capture features
`CHUNK_SIZE`	3000	Characters per LLM chunk
`MODEL_FAST`	gemma2:2b	Fast model for chunk processing
`MODEL_SMART`	gemma2:9b	Smart model for final report
`AGENTS_ENABLED`	True	Master switch for multi-agent system
`REDACT_SENSITIVE_DATA`	True	Remove secrets before cloud LLM calls

App Categories

Edit capture.py to customize:

LEARNING_APPS: TryHackMe, HackTheBox, Coursera, etc.
TERMINAL_APPS: CMD, PowerShell, Bash, WSL, etc.
TOOL_APPS: Burp Suite, Wireshark, Nmap, etc.
DISTRACTION_APPS: Netflix, YouTube, Discord, etc.
CYBERSEC_KEYWORDS: YouTube educational content detection

Components

File	Purpose
`capture.py`	Hybrid capture engine with OCR, keystrokes, URL tracking
`scribe.py`	LLM-powered report generator with parallel processing
`scribe_session.py`	Unified session launcher (main entry point)
`enhanced_capture.py`	Keystroke logger, URL tracker, state machine, error detector
`llm_provider.py`	LLM provider abstraction with batch processing
`model_router.py`	Fast/smart model provider selection
`doc_agent.py`	Documentation Agent (concept extraction)
`analysis_agent.py`	Analysis Agent (distraction patterns)
`agent_coordinator.py`	Multi-agent lifecycle orchestrator
`config.py`	Central configuration

Advanced Usage

Run Individual Agents

Documentation Agent Only:

python doc_agent.py logs/session_2026-05-04.jsonl 2026-05-04

Analysis Agent Only:

python analysis_agent.py logs/session_2026-05-04.jsonl logs/distraction_analysis.md

Report Generator Only:

python scribe.py 120  # Last 120 minutes

Custom LLM Providers

Edit config.py:

LLM_PROVIDER = "openai"  # or "anthropic", "gemini", "litellm"

Set API keys in config_local.py (gitignored):

OPENAI_API_KEY = "your-key-here"

Troubleshooting

No logs being generated

Check Tesseract path in config.py
Verify Ollama is running: ollama list
Check logs/ directory permissions

Report generation fails

Verify both models are pulled: ollama pull gemma2:9b and ollama pull gemma2:2b
Check Ollama is accessible at http://localhost:11434
Increase timeout in config.py: LLM_TIMEOUT = 300

Analysis Agent shows no distractions

Verify distraction apps are in DISTRACTION_APPS list in capture.py
Check log file has enough entries (minimum ~50 activities)

Components by Layer

Layer	Component	Type	Purpose
1	SessionManager	Core	Orchestrates session lifecycle
2	HybridCapture	Capture	Coordinates 8 capture implementations
2	ScreenshotCapture	Capture	Base screenshot + OCR engine
2	KeystrokeCapture	Capture	Event-driven keystroke logging
2	ActivityDetector	Capture	7-state machine for activity tracking
3	ProviderFactory	LLM	Creates LLM providers with caching
3	OllamaProvider	LLM	Local model support
3	OpenAIProvider	LLM	GPT-4/gpt-4o API
4	SessionRepository	Storage	JSON persistence for sessions
4	AnalysisRepository	Storage	Markdown + JSON report storage
5	DocumentationAgent	Agent	Markdown report generation
5	AnalysisAgent	Agent	Productivity analysis & insights
6	AgentCoordinator	Integration	Multi-agent orchestration

Extending the System

Adding a New LLM Provider

Create src/cyberscribe/llm/your_provider.py:

from ..core.base import BaseLLMProvider
from ..models import LLMRequest, LLMResponse

class YourProvider(BaseLLMProvider):
    def generate(self, request: LLMRequest) -> LLMResponse:
        return LLMResponse(
            provider="your_provider",
            model=self.model,
            prompt=request.prompt,
            response=output,
            usage={"tokens": n},
        )
    
    def is_available(self) -> bool:
        return True
    
    def get_model_name(self) -> str:
        return self.model
    
    def is_cloud_provider(self) -> bool:
        return False  # or True

Register in ProviderFactory (factory auto-discovers new providers)

Adding a New Agent

Create src/cyberscribe/agents/your_agent.py:

from ..core.base import BaseAgent
from ..models import Session

class YourAgent(BaseAgent):
    def initialize(self) -> None:
        pass
    
    def process(self, session: Session) -> Dict[str, Any]:
        return {"success": True, "results": {}}
    
    def get_name(self) -> str:
        return "YourAgent"
    
    def shutdown(self) -> None:
        pass

Register with AgentCoordinator:

from cyberscribe.agents import AgentCoordinator

coordinator = AgentCoordinator()
coordinator.register_agent("your_agent", YourAgent())

Documentation

QUICKSTART.md - Getting started with the OOP architecture
ARCHITECTURE.md - Detailed 6-layer architecture breakdown
TESTING.md - Complete testing strategy
REFACTORING_COMPLETE.md - Phase 1-6 summary
CONTRIBUTING.md - How to contribute

Testing

# Run all 167 tests
pytest tests/unit/ -v

# Run by phase
pytest tests/unit/test_core/ -v              # Phase 1: 31 tests
pytest tests/unit/test_capture/ -v           # Phase 2: 28 tests
pytest tests/unit/test_llm/ -v               # Phase 3: 27 tests
pytest tests/unit/test_storage/ -v           # Phase 4: 25 tests
pytest tests/unit/test_agents/ -v            # Phase 5: 33 tests
pytest tests/unit/test_integration/ -v       # Phase 6: 23 tests

# Coverage report
pytest tests/unit/ --cov=src/cyberscribe --cov-report=html

Performance

Test Execution: 167 tests in 0.70 seconds
Scalability: Handles 500+ activities per session
Batch Processing: Efficient multi-session workflows
Memory: Minimal overhead with repository pattern

License

MIT License - See LICENSE file for details

Status: Production Ready ✅

✅ Phase 1-6 Complete
✅ 167/167 Tests Passing
✅ 0.70s Test Execution
✅ Full OOP Architecture
✅ Comprehensive Documentation
✅ Error Resilience
✅ Extensible Design
✅ Type-Safe Implementation

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
config.py		config.py
config_validator.py		config_validator.py
environment_loader.py		environment_loader.py
error_sanitizer.py		error_sanitizer.py
log_rotation_manager.py		log_rotation_manager.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
scribe.py		scribe.py
scribe_session.py		scribe_session.py
secure_file_manager.py		secure_file_manager.py

Latest commit

History

Folders and files

Repository files navigation