hkos 1.0.0__py3-none-any.whl

hkos/__init__.py

@@ -0,0 +1,37 @@
+"""Hermes Knowledge OS (HKOS)
+============================
+An object-oriented file-based engineering knowledge database.
+
+DS-001 (Sprint 1): Foundation
+- HKOS as an importable module
+- Bootstrap, Configuration, Logger, Registry
+- Version and Health management
+"""
+
+from hkos.core.config import ConfigLoader
+from hkos.core.exceptions import (
+    ConfigurationError,
+    HKOSError,
+    InitializationError,
+    RuntimeErrorHKOS,
+    ValidationError,
+)
+from hkos.core.health import HealthManager
+from hkos.core.hkos import HKOS
+from hkos.core.logger import HKOSLogger
+from hkos.core.registry import Registry
+from hkos.core.version import VersionManager
+
+__all__ = [
+    "HKOS",
+    "VersionManager",
+    "ConfigLoader",
+    "HealthManager",
+    "Registry",
+    "HKOSLogger",
+    "HKOSError",
+    "ConfigurationError",
+    "InitializationError",
+    "RuntimeErrorHKOS",
+    "ValidationError",
+]

hkos/config/hkos-development.yaml

@@ -0,0 +1,151 @@
+# HKOS Development Configuration
+# Document: HKOS-14, DS-001
+# Version: 1.0.0
+
+hkos:
+  version: "1.0.0"
+  root: ./hkos
+  enabled: true
+
+core:
+  bootstrap:
+    auto_start: false
+    health_check_on_start: true
+  scheduler:
+    enabled: false
+
+logging:
+  level: DEBUG
+  file: ./hkos/logs/hkos.log
+  format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  max_size_mb: 10
+  backup_count: 3
+  namespace: hkos
+
+health:
+  check_interval_seconds: 60
+  components:
+    - config
+    - logger
+    - registry
+
+
+# ===== Retrieval Engine (DS-008) =====
+retrieval:
+  ranking:
+    topic_weight: 0.25
+    confidence_weight: 0.15
+    project_weight: 0.10
+    freshness_weight: 0.10
+    usage_weight: 0.05
+    canonical_weight: 0.15
+    references_weight: 0.05
+    success_weight: 0.05
+    campaign_weight: 0.05
+    decision_weight: 0.05
+    freshness_half_life_days: 90
+    # Верхние границы нормализации факторов (0 — фактор выключен;
+    # текущее поведение: usage/references/confirmations выключены,
+    # активируются заданием caps — Audit Remediation DS-009A, задача 4).
+    usage_cap: 0
+    references_cap: 0
+    confirmations_cap: 0
+    # Базовое число кандидатов фазы-2 ранжирования (см. refine_limit).
+    refine_limit_base: 60
+  selector:
+    top_n: 20
+  builder:
+    max_candidates: 200
+    keyword_limit: 50
+  traverser:
+    max_depth: 1
+    max_related: 10
+    relation_decay: 0.8
+  parser:
+    projects:
+      openwrt: "OpenWrt"
+      phoenix contact: "Phoenix Contact"
+      "phoenix": "Phoenix Contact"
+      terminal blocks: "Terminal Blocks"
+      hermes: "Hermes"
+    topics:
+      - routing
+      - firewall
+      - tproxy
+      - dns
+      - nftables
+      - policy routing
+      - sing-box
+      - udp
+      - vpn
+    entities:
+      - tproxy
+      - tcp
+      - udp
+      - nftables
+      - fwmark
+      - sing-box
+      - openwrt
+      - warp
+      - iptables
+      - tun
+    intents:
+      diagnostics: ["почему", "не работает", "диагностик", "причина", "debug"]
+      implementation: ["реализовать", "сделать", "настроить", "установить", "implement"]
+      research: ["исследовать", "как работает", "изучить", "research"]
+      architecture: ["архитектур", "спроектировать", "design"]
+      comparison: ["сравнить", "vs", "или", "compare"]
+      validation: ["проверить", "валидировать", "verify"]
+    stopwords: ["для", "и", "в", "на", "с", "по", "из", "у", "к", "о", "что", "как", "это", "не", "при", "до", "от", "за"]
+
+
+# ===== Context Builder (DS-009) =====
+context:
+  token_estimator:
+    characters_per_token: 4
+    words_per_token: 0.75
+  profiles:
+    SMALL: 4000
+    MEDIUM: 8000
+    LARGE: 16000
+    FULL: 0
+  snapshot:
+    dir: "snapshots"
+  serializer:
+    body_limit: 200
+    sections:
+      - TASK
+      - PROJECT
+      - CURRENT STATE
+      - CANONICAL KNOWLEDGE
+      - DECISIONS
+      - FAILURES
+      - ARTIFACTS
+      - CONFIGURATION
+      - OPEN QUESTIONS
+
+
+# ===== Hermes Integration Security (DS-012 §8) =====
+security:
+  enabled: true
+  require_confirmation:
+    migration: true
+    rollback: true
+  audit_log:
+    enabled: true
+  fallback:
+    retrieval: true
+    librarian_queue: true
+
+
+# ===== Performance Layer (DS-013 ЭТАП 5 §9) =====
+performance:
+  enabled: true
+  cache:
+    enabled: true
+    max_entries: 1000
+    ttl_seconds: 3600
+  context:
+    compression: normal
+  metrics:
+    enabled: true

hkos/config/hkos-production.yaml

@@ -0,0 +1,125 @@
+# HKOS Production Configuration
+# Document: DS-015 (ЭТАП 2 — Production Readiness)
+# Version: 1.0.0
+# Профиль: production (ConfigLoader(profile="production"))
+
+hkos:
+  version: "1.0.0"
+  root: ./hkos
+  enabled: true
+
+core:
+  bootstrap:
+    auto_start: true
+    health_check_on_start: true
+  scheduler:
+    enabled: false
+
+logging:
+  level: INFO
+  file: ./hkos/logs/hkos.log
+  format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  max_size_mb: 10
+  backup_count: 5
+  namespace: hkos
+
+health:
+  check_interval_seconds: 60
+  components:
+    - config
+    - logger
+    - registry
+
+# ===== Retrieval Engine (DS-008) =====
+# ===== Retrieval Engine (DS-008) =====
+retrieval:
+  ranking:
+    topic_weight: 0.25
+    confidence_weight: 0.15
+    project_weight: 0.10
+    freshness_weight: 0.10
+    usage_weight: 0.05
+    canonical_weight: 0.15
+    references_weight: 0.05
+    success_weight: 0.05
+    campaign_weight: 0.05
+    decision_weight: 0.05
+    freshness_half_life_days: 90
+    # Верхние границы нормализации факторов (0 — фактор выключен;
+    # текущее поведение: usage/references/confirmations выключены,
+    # активируются заданием caps — Audit Remediation DS-009A, задача 4).
+    usage_cap: 0
+    references_cap: 0
+    confirmations_cap: 0
+    # Базовое число кандидатов фазы-2 ранжирования (см. refine_limit).
+    refine_limit_base: 60
+  selector:
+    top_n: 20
+  builder:
+    max_candidates: 200
+    keyword_limit: 50
+  traverser:
+    max_depth: 1
+    max_related: 10
+    relation_decay: 0.8
+  parser:
+    projects:
+      openwrt: "OpenWrt"
+      phoenix contact: "Phoenix Contact"
+      "phoenix": "Phoenix Contact"
+      terminal blocks: "Terminal Blocks"
+      hermes: "Hermes"
+    topics:
+      - routing
+      - firewall
+      - tproxy
+      - dns
+      - nftables
+      - policy routing
+      - sing-box
+      - udp
+      - vpn
+    entities:
+      - tproxy
+      - tcp
+      - udp
+      - nftables
+      - fwmark
+      - sing-box
+      - openwrt
+      - warp
+      - iptables
+      - tun
+    intents:
+      diagnostics: ["почему", "не работает", "диагностик", "причина", "debug"]
+      implementation: ["реализовать", "сделать", "настроить", "установить", "implement"]
+      research: ["исследовать", "как работает", "изучить", "research"]
+      architecture: ["архитектур", "спроектировать", "design"]
+      comparison: ["сравнить", "vs", "или", "compare"]
+      validation: ["проверить", "валидировать", "verify"]
+    stopwords: ["для", "и", "в", "на", "с", "по", "из", "у", "к", "о", "что", "как", "это", "не", "при", "до", "от", "за"]
+
+# ===== Операционный режим (DS-015 ЭТАП 2) =====
+operations:
+  auto_snapshot: true
+  auto_index: true
+  retrieve_before_task: true
+  save_after_task: true
+  context_profile: medium
+
+# ===== Performance Layer (DS-013) =====
+performance:
+  enabled: true
+  cache:
+    enabled: true
+    max_entries: 1000
+    ttl_seconds: 3600
+  context:
+    compression: normal
+  metrics:
+    enabled: true
+
+# ===== Backup (DS-011/DS-015) =====
+backup:
+  enabled: true
+  keep_n: 5

hkos/config/logging.yaml

@@ -0,0 +1,44 @@
+# HKOS Logging Configuration
+version: 1
+disable_existing_loggers: false
+
+formatters:
+  standard:
+    format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  detailed:
+    format: "%(asctime)s [%(levelname)s] %(name)s (%(filename)s:%(lineno)d): %(message)s"
+
+handlers:
+  console:
+    class: logging.StreamHandler
+    level: DEBUG
+    formatter: standard
+    stream: ext://sys.stdout
+  file:
+    class: logging.handlers.RotatingFileHandler
+    level: DEBUG
+    formatter: detailed
+    filename: ./hkos/logs/hkos.log
+    maxBytes: 10485760
+    backupCount: 3
+  performance_file:
+    class: logging.handlers.RotatingFileHandler
+    level: INFO
+    formatter: detailed
+    filename: ./hkos/logs/performance.log
+    maxBytes: 10485760
+    backupCount: 3
+
+loggers:
+  hkos:
+    level: DEBUG
+    handlers: [console, file]
+    propagate: false
+  hkos.performance:
+    level: INFO
+    handlers: [performance_file]
+    propagate: false
+
+root:
+  level: WARNING
+  handlers: [console]

hkos/context/__init__.py

@@ -0,0 +1,58 @@
+"""HKOS Context Layer (DS-009)
+===========================
+Context Builder — формирование оптимального инженерного контекста
+из RetrievalResult (минимальный по объёму, максимальный по полезности).
+
+Использует: RetrievalResult (DS-008), SnapshotLoader (read-only),
+Query Contract. Запрещены: StorageEngine/IndexStore/JSON/поиск.
+"""
+
+from hkos.context.context_builder import (
+    PROFILE_FULL,
+    PROFILE_LARGE,
+    PROFILE_MEDIUM,
+    PROFILE_SMALL,
+    VALID_PROFILES,
+    ContextBuilder,
+)
+from hkos.context.context_manager import ContextManager
+from hkos.context.context_optimizer import ContextOptimizer
+from hkos.context.context_serializer import ContextSerializer
+from hkos.context.context_statistics import ContextStatistics
+from hkos.context.context_validator import ContextValidator
+from hkos.context.exceptions import ContextError, ContextValidationError
+from hkos.context.models import (
+    ContextDocument,
+    ContextExplanation,
+    ContextItem,
+)
+from hkos.context.snapshot_loader import (
+    SnapshotDocument,
+    SnapshotLoader,
+    SnapshotReader,
+)
+from hkos.context.token_estimator import TokenEstimate, TokenEstimator
+
+__all__ = [
+    "ContextBuilder",
+    "ContextManager",
+    "ContextOptimizer",
+    "ContextSerializer",
+    "ContextValidator",
+    "ContextStatistics",
+    "TokenEstimator",
+    "TokenEstimate",
+    "SnapshotLoader",
+    "SnapshotReader",
+    "SnapshotDocument",
+    "ContextDocument",
+    "ContextItem",
+    "ContextExplanation",
+    "ContextError",
+    "ContextValidationError",
+    "PROFILE_SMALL",
+    "PROFILE_MEDIUM",
+    "PROFILE_LARGE",
+    "PROFILE_FULL",
+    "VALID_PROFILES",
+]

hkos/context/context_builder.py

@@ -0,0 +1,199 @@
+"""HKOS Context Builder (DS-009 §4-6, IP-009)
+==========================================
+Публичный фасад Context Layer.
+
+Публичный API (ровно эти методы):
+    build, optimize, serialize, statistics, validate,
+    estimate_tokens, explain
+
+Допустимые зависимости: RepositoryManager (не используется напрямую —
+через RetrievalResult), RetrievalEngine, SnapshotLoader, Query Contract.
+
+Запрещено: поиск, StorageEngine, IndexStore, JSON, изменение
+Repository/Snapshot/RetrievalResult (архитектурные тесты).
+"""
+
+
+from hkos.context.context_manager import ContextManager
+from hkos.context.context_optimizer import ContextOptimizer
+from hkos.context.context_serializer import ContextSerializer
+from hkos.context.context_statistics import ContextStatistics
+from hkos.context.context_validator import ContextValidator
+from hkos.context.models import ContextDocument, ContextExplanation
+from hkos.context.snapshot_loader import SnapshotLoader
+from hkos.context.token_estimator import TokenEstimate, TokenEstimator
+from hkos.core.config import ConfigLoader
+from hkos.core.logger import HKOSLogger
+from hkos.index.validation import ValidationResult
+from hkos.retrieval.retrieval_engine import RetrievalResult
+
+__all__ = ["ContextBuilder"]
+
+PROFILE_SMALL: str = "SMALL"
+PROFILE_MEDIUM: str = "MEDIUM"
+PROFILE_LARGE: str = "LARGE"
+PROFILE_FULL: str = "FULL"
+
+VALID_PROFILES: frozenset[str] = frozenset({
+    PROFILE_SMALL, PROFILE_MEDIUM, PROFILE_LARGE, PROFILE_FULL,
+})
+
+
+class ContextBuilder:
+    """Публичный фасад Context Builder (7 методов)."""
+
+    def __init__(
+        self,
+        config: ConfigLoader,
+        logger: HKOSLogger,
+        loader: SnapshotLoader | None = None,
+        manager: ContextManager | None = None,
+    ) -> None:
+        """Инициализация Context Builder.
+
+        Args:
+            config: ConfigLoader (секция context.*).
+            logger: HKOSLogger.
+            loader: SnapshotLoader (read-only); по умолчанию без снимков.
+            manager: ContextManager; создаётся по умолчанию из конфигурации.
+
+        """
+        self._config = config
+        self._logger = logger
+
+        # Коэффициенты из конфигурации (без захардкоженных чисел)
+        cpt = config.get("context.token_estimator.characters_per_token", 4)
+        wpt = config.get("context.token_estimator.words_per_token", 1)
+        characters_per_token = float(cpt) if isinstance(cpt, (int, float)) else 4.0
+        words_per_token = float(wpt) if isinstance(wpt, (int, float)) else 1.0
+        self._estimator = TokenEstimator(characters_per_token, words_per_token)
+
+        # Профили (лимиты токенов)
+        raw_profiles = config.get("context.profiles", {})
+        profile_limits: dict[str, int] = {}
+        if isinstance(raw_profiles, dict):
+            for name, limit in raw_profiles.items():
+                if isinstance(limit, int):
+                    profile_limits[str(name)] = limit
+
+        # Секции сериализатора
+        raw_sections = config.get("context.serializer.sections", None)
+        sections = (
+            [str(s) for s in raw_sections]
+            if isinstance(raw_sections, list)
+            else None
+        )
+
+        self._loader = loader if loader is not None else SnapshotLoader()
+        body_limit_raw = config.get("context.serializer.body_limit", 200)
+        body_limit = int(body_limit_raw) if isinstance(body_limit_raw, int) else 200
+        self._serializer = ContextSerializer(sections, body_limit=body_limit)
+        self._optimizer = ContextOptimizer(self._estimator, profile_limits)
+        self._validator = ContextValidator(self._serializer)
+        self._manager = (
+            manager
+            if manager is not None
+            else ContextManager(
+                self._loader, self._optimizer, self._serializer,
+                self._validator, self._estimator,
+            )
+        )
+
+    # --- Публичный API ---
+
+    def build(
+        self,
+        result: RetrievalResult,
+        project_id: str,
+        campaign_id: str | None = None,
+        profile: str = PROFILE_MEDIUM,
+        include_history: bool = False,
+    ) -> ContextDocument:
+        """Построить контекст (полный конвейер).
+
+        Args:
+            result: RetrievalResult (DS-008).
+            project_id: UUID проекта.
+            campaign_id: UUID кампании (опционально).
+            profile: SMALL/MEDIUM/LARGE/FULL.
+            include_history: Включить исторические статусы.
+
+        Returns:
+            ContextDocument.
+
+        """
+        self._logger.info("Context Started")
+        if profile not in VALID_PROFILES:
+            profile = PROFILE_MEDIUM
+        context = self._manager.build(
+            result, project_id, campaign_id, profile, include_history
+        )
+        self._logger.info("Snapshot Loaded")
+        self._logger.info("Knowledge Added")
+        self._logger.info("Knowledge Removed")
+        self._logger.info("Optimization Completed")
+        self._logger.info("Serialization Completed")
+        self._logger.info("Context Delivered")
+        return context
+
+    def optimize(
+        self, context: ContextDocument, include_history: bool = False
+    ) -> ContextDocument:
+        """Оптимизировать контекст (dedup/фильтры/canonical merge/бюджет)."""
+        return self._optimizer.optimize(context, include_history)
+
+    def serialize(self, context: ContextDocument) -> str:
+        """Сериализовать контекст (стабильный порядок секций)."""
+        return self._serializer.serialize(context)
+
+    def statistics(self, context: ContextDocument) -> dict[str, object]:
+        """Статистика контекста."""
+        return ContextStatistics.calculate(context)
+
+    def validate(self, context: ContextDocument) -> ValidationResult:
+        """Проверить документ контекста."""
+        return self._validator.validate(context)
+
+    def estimate_tokens(self, text: str) -> TokenEstimate:
+        """Оценить размер текста (Characters/Words/Estimated Tokens)."""
+        return self._estimator.estimate(text)
+
+    def explain(self, context: ContextDocument) -> list[ContextExplanation]:
+        """Объяснение каждого элемента (почему включён/исключён,
+        источник, экономия токенов).
+        """
+        explanations: list[ContextExplanation] = []
+        for item in context.items:
+            explanations.append(
+                ContextExplanation(
+                    entity_id=getattr(item.entity, "id", ""),
+                    why_included=(
+                        f"{item.reason} (source={item.source}, "
+                        f"score={item.score:.2f})"
+                    ),
+                    why_excluded="",
+                    source=item.source,
+                    token_savings=0,
+                )
+            )
+        for item in context.excluded:
+            text = str(
+                getattr(item.entity, "title", "")
+                or getattr(item.entity, "name", "")
+                or ""
+            )
+            explanations.append(
+                ContextExplanation(
+                    entity_id=getattr(item.entity, "id", ""),
+                    why_included="",
+                    why_excluded=item.excluded_reason,
+                    source=item.source,
+                    token_savings=self._estimator.estimate(text).estimated_tokens,
+                )
+            )
+        return explanations
+
+    @property
+    def loader(self) -> SnapshotLoader:
+        """SnapshotLoader (read-only)."""
+        return self._loader