Skip to content

Code Overview

Jump to bottom
Nick edited this page Nov 21, 2025 · 3 revisions

PATAS Core v2 - Code Overview

Version: 2.0

Quick reference guide for navigating the PATAS codebase.

Directory Structure

PATAS/
├── app/                    # Main application code
│   ├── api/               # HTTP API layer (FastAPI)
│   ├── models.py          # SQLAlchemy domain models
│   ├── repositories.py    # Data access layer
│   ├── v2_*.py           # Core v2 services
│   ├── config.py         # Configuration
│   └── cli.py            # Command-line interface
├── integration/  # Platform-specific integration layer
│   ├── adapters.py       # Message adapters
│   ├── backends.py        # Rule backends
│   └── cli.py            # PoC CLI
├── tests/                 # Test suite
├── legacy/               # Legacy v1 components (reference only)
├── docs/                 # Additional documentation
└── scripts/              # Utility scripts

Core Components

Domain Models (app/models.py)

  • Message - Normalized message storage
  • Pattern - Discovered spam patterns
  • Rule - SQL blocking rules with lifecycle
  • RuleEvaluation - Rule evaluation metrics

Data Access (app/repositories.py)

  • MessageRepository - Message CRUD operations
  • PatternRepository - Pattern management
  • RuleRepository - Rule management
  • RuleEvaluationRepository - Evaluation metrics access

Core Services (app/v2_*.py)

Ingestion (v2_ingestion.py)

  • TASLogIngester - Ingest logs from API/storage

Pattern Mining (v2_pattern_mining.py)

  • PatternMiningPipeline - Discover patterns from messages

Rule Lifecycle (v2_rule_lifecycle.py)

  • RuleLifecycleService - Manage rule state machine

Shadow Evaluation (v2_shadow_evaluation.py)

  • ShadowEvaluationService - Evaluate rules safely

Promotion (v2_promotion.py)

  • PromotionService - Promote/deprecate rules automatically

Rule Backend (v2_rule_backend.py)

  • RuleBackend - Abstract interface for rule export
  • SqlRuleBackend - SQL export
  • RolRuleBackend - ROL format export

LLM Engine (v2_llm_engine.py)

  • PatternMiningEngine - Abstract interface for LLM
  • OpenAIPatternMiningEngine - OpenAI implementation

SQL Safety (v2_sql_safety.py)

  • SQL validation and sanitization

Semantic Mining (v2_semantic_mining.py)

  • Semantic clustering and pattern discovery

Embedding Engine (v2_embedding_engine.py)

  • Embedding generation for semantic similarity

Safety Mode (v2_safety_mode.py)

  • Safety profile management

Pattern Quality (v2_pattern_quality.py, v2_pattern_quality_tiers.py)

  • Pattern quality assessment and tier assignment

SQL LLM Validator (v2_sql_llm_validator.py)

  • LLM-based SQL rule validation

API Layer (app/api/)

Main App (api/main.py)

  • FastAPI application with all endpoints
  • Thin orchestration layer over Core services

Models (api/models.py)

  • Pydantic request/response models

Entry Point (api/run.py)

  • Server startup script

Configuration (app/config.py)

  • Settings - Pydantic settings with environment variable support
  • All configuration via environment variables or .env file

CLI (app/cli.py)

  • patas ingest-logs - Ingest logs
  • patas mine-patterns - Run pattern mining
  • patas eval-rules - Evaluate shadow rules
  • patas promote-rules - Promotion/rollback
  • patas safety-eval - Run safety evaluation
  • patas explain-rule - Explain a single rule
  • patas demo-tg - Run your platform demo

Key Design Principles

  1. Generic Core - No client-specific logic in core
  2. Extension Points - Interfaces for backends, engines, adapters
  3. Thin API Layer - No business logic, just orchestration
  4. Explicit Flows - Clear, testable, understandable
  5. Safety First - SQL validation, rule validation, metrics

Entry Points

API Server

uvicorn app.api.main:app --host 0.0.0.0 --port 8000
# or
patas-api

CLI

patas <command> [options]

Testing

All tests in tests/ directory:

  • test_v2_*.py - Core v2 component tests
  • test_api.py - API endpoint tests
  • test_*.py - Other component tests

Run tests:

pytest tests/

Extension Points

To extend PATAS Core:

  1. Rule Backend - Implement RuleBackend interface
  2. LLM Engine - Implement PatternMiningEngine interface
  3. Message Adapter - Extend MessageRepository or create adapter
  4. Pattern Profile - Add pattern types/extraction logic

See Architecture for detailed extension guide.

For New Developers

Start here:

  1. Read Architecture for high-level understanding
  2. Review app/models.py for domain models
  3. Check app/api/main.py for API endpoints
  4. Look at app/v2_pattern_mining.py for core service example

Key files to understand:

  • app/models.py - Data structures
  • app/repositories.py - Data access
  • app/v2_pattern_mining.py - Pattern discovery
  • app/v2_promotion.py - Rule lifecycle
  • app/api/main.py - API layer

Related Documentation

Clone this wiki locally