Eve library

Psyche Domain: Code Quality Audit Report

Guide

Revision 1

On this page

This document provides a comprehensive code quality analysis of the Serwaa platform (source codebase for the Psyche domain migration).

Audit Date: 2026-01-24 Scope: Full codebase code quality review Tools Used: Static analysis, manual review

Table of Contents#

  1. Executive Summary
  2. Critical Issues
  3. High Severity Issues
  4. Medium Severity Issues
  5. Low Severity Issues
  6. Technical Debt Backlog
  7. Remediation Plan

Executive Summary#

Codebase Statistics#

Metric Value
Python Files 808
TypeScript/TSX Files 14
Test Files 486
Total Lines of Code ~508,000

Findings Overview#

Severity Count Category
Critical 1 Syntax error blocking import
High 343+ Bare exception handlers
High 30+ Exception silencing
High 40+ Untyped Any parameters
Medium-High 30+ Files >1000 lines
Medium 20+ Type ignore comments
Medium 6+ Print statements in production
Medium 4+ Large React components
Low 4 Empty initialization files

Technical Debt Summary#

text
┌─────────────────────────────────────────────────────────────────┐
│                    TECHNICAL DEBT DISTRIBUTION                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Error Handling      ████████████████████████████████  45%       │
│  Code Complexity     ████████████████                  25%       │
│  Type Safety         ████████████                      15%       │
│  Duplication         ██████                            10%       │
│  Documentation       ████                               5%       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Critical Issues#

CQ-C01: Syntax Error Blocking Knowledge Base Import#

Severity: CRITICAL Impact: Entire knowledge-base service cannot start

Location#

text
serwaa/services/knowledge-base/src/knowledge_base/ingestion/cleaning.py:316

Problem#

python
# Line 316 - SYNTAX ERROR
"â€"": "-",  # Malformed smart quote character (corrupted UTF-8)

The file contains corrupted UTF-8 byte sequences from smart quote characters, causing a syntax error that prevents the module from being imported.

Remediation#

python
# BEFORE (Corrupted)
"â€"": "-",
"’": "'",

# AFTER (Fixed)
"—": "-",   # Em dash
"'": "'",   # Right single quote

Priority: P0 - Fix immediately (blocks service startup)


High Severity Issues#

CQ-H01: Bare Exception Handlers (343+ instances)#

Severity: HIGH Impact: Silent failures hide bugs, impossible to debug issues

Problem Pattern#

python
# Pattern 1: No context or logging
try:
    await self.cleanup()
except Exception:
    pass  # Failure silently ignored

# Pattern 2: Generic exception catch-all
try:
    await self.connect()
except Exception as e:
    print(f"Error: {e}")  # Not logged, lost in production

Affected Files (Top Offenders)#

File Instances Description
zoom/browser.py 18+ Browser automation failures
meet/browser.py 13+ Browser automation failures
realtime_assistance.py 10+ AI assistance failures
meet/api.py 4+ API call failures
zoom/adapter.py 4+ Stream handling failures

Examples#

python
# serwaa/services/video-conferencing/src/video_conferencing/zoom/browser.py

# Lines 239, 361, 367, 381, 388, 403, 410, 417, 424, 437, 445, 456, 467
try:
    await self._page.click(selector)
except Exception:
    pass  # Click failure silently ignored

# serwaa/services/video-conferencing/src/video_conferencing/meet/__init__.py
# Lines 86, 94, 106, 113, 125, 141, 154
try:
    from video_conferencing.meet.auth import AuthManager
except ModuleNotFoundError:
    pass  # Can't distinguish optional from broken imports

Remediation#

python
# BEFORE (Bad)
try:
    await self.connect()
except Exception:
    pass

# AFTER (Good)
try:
    await self.connect()
except ConnectionError as e:
    logger.warning("Connection failed, will retry", error=str(e))
    raise
except TimeoutError as e:
    logger.error("Connection timeout", error=str(e))
    raise ConnectionTimeoutError from e
except Exception as e:
    logger.exception("Unexpected error during connection")
    raise

CQ-H02: Invalid Escape Sequence#

Severity: HIGH Impact: Will become syntax error in Python 3.12+

Location#

text
serwaa/tests/utils/matchers.py:145

Problem#

python
# BEFORE (Warning, becomes error in Python 3.12)
pattern = "\w+"  # SyntaxWarning: invalid escape sequence '\w'

# AFTER (Fixed)
pattern = r"\w+"  # Raw string prefix

CQ-H03: Excessive Any Type Usage (40+ instances)#

Severity: HIGH Impact: Type safety bypass, runtime errors not caught by type checker

Problem Patterns#

python
# Pattern 1: Untyped function parameters
def push(self, timestamp_ns: int, data: Any) -> bool:
    # Should be: data: bytes | np.ndarray | AudioFrame

# Pattern 2: Untyped class attributes
self._playwright: Any = None  # Should import types from playwright
self._browser: Any = None
self._context: Any = None

# Pattern 3: Untyped kwargs
def create(**kwargs: Any) -> Model:
    # Should use: TypedDict or document expected keys

Affected Files#

File Instances Issue
zoom/browser.py 4 Playwright objects untyped
meet/routing.py 1 Route handler untyped
meet/adapter.py 2 Audio/video sources untyped
teams/bot_adapter.py 3 Microsoft SDK objects
large_meeting.py 1 Optimization config
multi_participant.py 4 Tracking data untyped

Remediation#

python
# BEFORE
def push(self, timestamp_ns: int, data: Any) -> bool:
    ...

# AFTER
from typing import Union
from numpy import ndarray

AudioData = Union[bytes, ndarray, "AudioFrame"]

def push(self, timestamp_ns: int, data: AudioData) -> bool:
    ...

CQ-H04: Type Ignore Comments (20+ instances)#

Severity: HIGH Impact: Type safety bypassed without documentation

Affected Files#

File Lines Reason
large_meeting.py 629, 650, 668 Numpy operations
codecs.py 30, 36, 42 External library types
progress.py 140, 145 OCR library types

Remediation#

Each # type: ignore should either:

  1. Be removed by fixing the type issue
  2. Have a specific error code: # type: ignore[arg-type]
  3. Have a comment explaining why it's necessary
python
# BEFORE
result = np.array(data)  # type: ignore

# AFTER
result = np.array(data)  # type: ignore[arg-type] - numpy stubs incomplete for this overload

Medium Severity Issues#

CQ-M01: Excessive File Sizes (30+ files >1000 lines)#

Severity: MEDIUM-HIGH Impact: Hard to maintain, violates Single Responsibility Principle

Largest Python Files#

File Lines Issues
stream_capture.py 2,878 50+ classes, 100+ functions
skill_synthesis.py 2,851 Code gen, testing, verification mixed
body_language.py 2,754 Pose, gestures, posture combined
speaking.py 2,686 Speaking, lip-sync, expressions
audio_separation.py 2,653 Diarization, separation, voiceprints
face_analysis.py 2,623 Multiple analysis types
gestures.py 2,578 Complex gesture detection
emotion_tracking.py 2,516 Multi-modal emotion analysis
large_meeting.py 2,383 Meeting optimization
behavioral_cloning.py 2,282 Learning and synthesis

Largest TypeScript Files#

File Lines Issues
settings/page.tsx 1,657 Single massive component
avatar-form.tsx 1,327 Mixed concerns
use-aria.ts 1,011 Single hook doing too much
help-content.tsx 979 Needs decomposition
knowledge/[id]/page.tsx 966 Multiple features

Remediation Strategy#

text
# BEFORE: stream_capture.py (2,878 lines)
class VideoCapture: ...
class AudioCapture: ...
class ScreenCapture: ...
class StreamEncoder: ...
class StreamDecoder: ...
# 50+ more classes

# AFTER: Split into modules
stream_capture/
├── __init__.py
├── video.py          # VideoCapture
├── audio.py          # AudioCapture
├── screen.py         # ScreenCapture
├── encoding.py       # StreamEncoder, StreamDecoder
├── types.py          # Shared types
└── utils.py          # Common utilities

CQ-M02: Print Statements in Production Code#

Severity: MEDIUM Impact: Errors lost in CI/CD, no structured logging

Affected Files#

File Lines Usage
embedding/stores.py 279, 326, 370, 449, 496, 563 Error printing
scheduling.py 332 Debug output
benchmark/ci.py 138-140 Progress output
benchmark/dashboard.py 542-544 Dashboard output

Current Code#

python
# serwaa/services/knowledge-base/src/knowledge_base/embedding/stores.py
try:
    await self.save(embedding)
except Exception as e:
    print(f"Error saving embedding: {e}")  # Lost in production!

Remediation#

python
import structlog

logger = structlog.get_logger(__name__)

try:
    await self.save(embedding)
except Exception as e:
    logger.exception(
        "Failed to save embedding",
        embedding_id=embedding.id,
        error=str(e)
    )
    raise

CQ-M03: Code Duplication in Adapters#

Severity: MEDIUM Impact: Bug fixes need to be applied in multiple places

Duplicated Pattern: Video Conferencing Adapters#

python
# Similar patterns in:
# - meet/adapter.py
# - meet/browser_adapter.py
# - zoom/adapter.py
# - zoom/browser_adapter.py
# - zoom/hybrid_adapter.py
# - teams/bot_adapter.py
# - webex/adapter.py

class PlatformAdapter:
    async def connect(self):
        # Similar connection logic
        ...

    async def disconnect(self):
        # Similar cleanup logic
        ...

    async def send_audio(self, data: bytes):
        # Similar audio handling
        ...

Remediation#

python
# Create base adapter
class BaseVideoAdapter(ABC):
    """Base class for all video conferencing adapters."""

    @abstractmethod
    async def connect(self) -> None:
        """Establish connection to platform."""
        ...

    async def _handle_connection_error(self, error: Exception) -> None:
        """Common error handling logic."""
        logger.exception("Connection failed", platform=self.platform_name)
        await self._cleanup()
        raise

# Inherit in specific adapters
class ZoomAdapter(BaseVideoAdapter):
    platform_name = "zoom"

    async def connect(self) -> None:
        try:
            # Zoom-specific connection logic
            ...
        except Exception as e:
            await self._handle_connection_error(e)

CQ-M04: TypeScript Type Assertion Abuse#

Severity: MEDIUM Impact: Runtime type errors not caught at compile time

Examples#

typescript
// serwaa/services/admin-dashboard/src/api/client.ts

// BEFORE (Unsafe)
error = (await response.json()) as typeof error; // Unchecked assertion
return {} as T; // Returns empty object unsafely
return response.json() as Promise<T>; // Assertion bypass

// AFTER (Safe)
const data = await response.json();
if (!isValidResponse<T>(data)) {
  throw new ValidationError('Invalid response format');
}
return data;

CQ-M05: Large React Components Violating SRP#

Severity: MEDIUM Impact: Hard to test, reuse, and maintain

Example: settings/page.tsx (1,657 lines)#

typescript
// BEFORE: Monolithic component
export default function SettingsPage() {
    // State for API keys
    const [apiKeys, setApiKeys] = useState();
    // State for user preferences
    const [preferences, setPreferences] = useState();
    // State for integrations
    const [integrations, setIntegrations] = useState();
    // ... 1600 more lines

    return (
        <div>
            {/* API Key section */}
            {/* Preferences section */}
            {/* Integrations section */}
            {/* Billing section */}
            {/* Team section */}
        </div>
    );
}

// AFTER: Composed components
export default function SettingsPage() {
    return (
        <SettingsLayout>
            <ApiKeysSection />
            <PreferencesSection />
            <IntegrationsSection />
            <BillingSection />
            <TeamSection />
        </SettingsLayout>
    );
}

Low Severity Issues#

CQ-L01: Empty Test Files#

Severity: LOW Impact: Minimal (namespace packages)

Files#

text
tests/integration/__init__.py
tests/integration/pipeline/__init__.py
tests/avatar_engine/__init__.py
tests/avatar_engine/utils/__init__.py

These are likely intentional for namespace packages.


CQ-L02: Stale TODO Comments#

Severity: LOW Impact: Technical debt not tracked

Examples#

python
# serwaa/services/video-conferencing/src/video_conferencing/teams/media/codecs.py:976
# TODO: Add VP9Codec

# Various files
# TODO: Implement retry logic
# TODO: Add validation
# FIXME: Race condition

Remediation#

Convert TODOs to tracked issues:

python
# BEFORE
# TODO: Add VP9Codec

# AFTER
# TECH-DEBT-123: Add VP9Codec support
# See: https://github.com/project/issues/123

Technical Debt Backlog#

Priority 1: Blocking Issues#

ID Issue File Effort
TD-001 Syntax error in cleaning.py knowledge-base/.../cleaning.py:316 0.5h
TD-002 Invalid escape sequence tests/utils/matchers.py:145 0.5h

Priority 2: Error Handling#

ID Issue Files Effort
TD-010 Bare exceptions in zoom/browser.py zoom/browser.py 4h
TD-011 Bare exceptions in meet/browser.py meet/browser.py 3h
TD-012 Bare exceptions in realtime_assistance.py realtime_assistance.py 2h
TD-013 Exception silencing in init.py files */__init__.py 4h
TD-014 Replace print() with logging embedding/stores.py + others 2h

Priority 3: Type Safety#

ID Issue Files Effort
TD-020 Remove Any types Multiple 8h
TD-021 Document type ignores Multiple 4h
TD-022 Add missing return types Multiple 4h
TD-023 Fix TypeScript any usage admin-dashboard/ 4h

Priority 4: Code Organization#

ID Issue Files Effort
TD-030 Split stream_capture.py stream_capture.py 8h
TD-031 Split skill_synthesis.py skill_synthesis.py 6h
TD-032 Split body_language.py body_language.py 6h
TD-033 Extract BaseVideoAdapter */adapter.py 8h
TD-034 Split settings/page.tsx settings/page.tsx 4h

Priority 5: Documentation#

ID Issue Files Effort
TD-040 Add module docstrings */__init__.py 4h
TD-041 Document public APIs Multiple 8h
TD-042 Convert TODOs to issues Multiple 2h

Remediation Plan#

Week 1: Critical & Blocking#

Goal: Unblock all services

  • Fix syntax error in cleaning.py:316
  • Fix escape sequence in matchers.py:145
  • Run full test suite to verify fixes
  • Set up pre-commit hooks for linting

Week 2: High-Priority Error Handling#

Goal: Improve debuggability

  • Replace bare exceptions in zoom/browser.py (18 instances)
  • Replace bare exceptions in meet/browser.py (13 instances)
  • Add structured logging to realtime_assistance.py
  • Replace print() with logging in embedding/stores.py

Week 3-4: Type Safety#

Goal: Enable strict type checking

  • Replace Any types with specific types
  • Document or fix all # type: ignore comments
  • Add missing return type annotations
  • Enable mypy strict mode

Month 2: Code Organization#

Goal: Improve maintainability

  • Split stream_capture.py into modules
  • Split skill_synthesis.py into modules
  • Extract BaseVideoAdapter base class
  • Split settings/page.tsx into components

Ongoing: Quality Gates#

  • Enforce test coverage >80%
  • Enable ESLint strict rules
  • Add complexity limits (max 50 lines per function)
  • Regular code review focused on duplication

Appendix: Configuration Files#

toml
# pyproject.toml
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_any_explicit = true

[[tool.mypy.overrides]]
module = "third_party.*"
ignore_missing_imports = true
toml
# pyproject.toml
[tool.ruff]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # Pyflakes
    "I",   # isort
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "UP",  # pyupgrade
    "ARG", # flake8-unused-arguments
    "SIM", # flake8-simplify
]
ignore = [
    "E501", # line too long (handled by formatter)
]

[tool.ruff.per-file-ignores]
"tests/*" = ["ARG"]
json
{
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/strict",
    "plugin:@typescript-eslint/stylistic"
  ],
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "max-lines": ["warn", 500],
    "complexity": ["warn", 20]
  }
}

Pre-commit Configuration#

yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]

  - repo: local
    hooks:
      - id: no-print
        name: Check for print statements
        entry: '^\s*print\('
        language: pygrep
        types: [python]
        exclude: ^tests/