reskpoints 0.1.0__py3-none-any.whl

reskpoints/__init__.py

@@ -0,0 +1,29 @@
+from .agent_logger import AgentLogger
+from .config import AgentLoggerConfig
+from .decorator import log_action
+from .masking import FieldMasker
+from .models import ActionLog, LogResult
+from .platforms import (
+    BasePlatform,
+    ConsolePlatform,
+    FilePlatform,
+    MockPlatform,
+    WebhookPlatform,
+)
+
+__version__ = "0.1.0"
+__author__ = "RESK Security"
+
+__all__ = [
+    "AgentLogger",
+    "AgentLoggerConfig",
+    "log_action",
+    "FieldMasker",
+    "ActionLog",
+    "LogResult",
+    "BasePlatform",
+    "ConsolePlatform",
+    "FilePlatform",
+    "MockPlatform",
+    "WebhookPlatform",
+]

reskpoints/agent_logger.py

@@ -0,0 +1,179 @@
+import os
+import platform
+import random
+import time
+from pathlib import Path
+from typing import Any
+
+from .config import AgentLoggerConfig
+from .masking import FieldMasker
+from .models import ActionLog, LogResult, PlatformHealth
+from .platforms import (
+    BasePlatform,
+    ConsolePlatform,
+    FilePlatform,
+    MockPlatform,
+    WebhookPlatform,
+)
+
+
+class AgentLogger:
+    def __init__(self, config: AgentLoggerConfig | str | Path | None = None):
+        if isinstance(config, (str, Path)):
+            self.config = AgentLoggerConfig.from_file(str(config))
+        elif isinstance(config, AgentLoggerConfig):
+            self.config = config
+        else:
+            self.config = AgentLoggerConfig.from_file("reskpoints.yaml")
+
+        self.environment = self.config.environment
+        self.host = platform.node()
+
+        self.masker = FieldMasker(
+            sensitive_fields=self.config.sensitive_fields,
+            enabled=self.config.masking_enabled,
+        )
+
+        self.platforms: dict[str, BasePlatform] = {}
+        self._init_platforms()
+
+    def _init_platforms(self):
+        platform_configs = self.config.platforms_config
+        registry: dict[str, type[BasePlatform]] = {
+            "console": ConsolePlatform,
+            "file": FilePlatform,
+            "webhook": WebhookPlatform,
+        }
+
+        try:
+            from .platforms.prometheus import PrometheusPlatform
+            registry["prometheus"] = PrometheusPlatform
+        except ImportError:
+            pass
+
+        try:
+            from .platforms.datadog import DatadogPlatform
+            registry["datadog"] = DatadogPlatform
+        except ImportError:
+            pass
+
+        for name, platform_cls in registry.items():
+            cfg = platform_configs.get(name, {})
+            if cfg.get("enabled", False):
+                instance = platform_cls(cfg)
+                self.platforms[name] = instance
+
+        if not self.platforms:
+            self.platforms["mock"] = MockPlatform({"enabled": True})
+
+    def log(
+        self,
+        agent_id: str,
+        action: str,
+        probability: float = 1.0,
+        params: dict[str, Any] | None = None,
+        result: Any = None,
+        success: bool = True,
+        duration_ms: float | None = None,
+        session_id: str | None = None,
+        correlation_id: str | None = None,
+        sensitive_fields: list[str] | None = None,
+        **metadata: Any,
+    ) -> list[LogResult]:
+        entry = ActionLog(
+            agent_id=agent_id,
+            session_id=session_id,
+            correlation_id=correlation_id,
+            action=action,
+            probability=probability,
+            parameters=params or {},
+            result=result,
+            success=success,
+            duration_ms=duration_ms,
+            environment=self.environment,
+            host=self.host,
+            metadata=metadata,
+            sensitive_fields=sensitive_fields or [],
+        )
+        return self.log_action(entry)
+
+    def log_action(self, entry: ActionLog) -> list[LogResult]:
+        rate = self.config.get_sampling_rate(entry.action)
+        if rate < 1.0 and random.random() > rate:
+            return [LogResult(success=True, platform="sampling_skip", action_id=entry.id)]
+
+        if self.config.masking_enabled:
+            entry.parameters = self.masker.mask(
+                entry.parameters,
+                extra_fields=entry.sensitive_fields,
+            )
+
+        results: list[LogResult] = []
+        for platform in self.platforms.values():
+            result = platform.emit(entry)
+            results.append(result)
+        return results
+
+    async def alog(
+        self,
+        agent_id: str,
+        action: str,
+        probability: float = 1.0,
+        params: dict[str, Any] | None = None,
+        result: Any = None,
+        success: bool = True,
+        duration_ms: float | None = None,
+        session_id: str | None = None,
+        correlation_id: str | None = None,
+        sensitive_fields: list[str] | None = None,
+        **metadata: Any,
+    ) -> list[LogResult]:
+        entry = ActionLog(
+            agent_id=agent_id,
+            session_id=session_id,
+            correlation_id=correlation_id,
+            action=action,
+            probability=probability,
+            parameters=params or {},
+            result=result,
+            success=success,
+            duration_ms=duration_ms,
+            environment=self.environment,
+            host=self.host,
+            metadata=metadata,
+            sensitive_fields=sensitive_fields or [],
+        )
+        return await self.alog_action(entry)
+
+    async def alog_action(self, entry: ActionLog) -> list[LogResult]:
+        rate = self.config.get_sampling_rate(entry.action)
+        if rate < 1.0 and random.random() > rate:
+            return [LogResult(success=True, platform="sampling_skip", action_id=entry.id)]
+
+        if self.config.masking_enabled:
+            entry.parameters = self.masker.mask(
+                entry.parameters,
+                extra_fields=entry.sensitive_fields,
+            )
+
+        import asyncio
+
+        results: list[LogResult] = []
+        tasks = [platform.aemit(entry) for platform in self.platforms.values()]
+        for coro in asyncio.as_completed(tasks):
+            result = await coro
+            results.append(result)
+        return results
+
+    def flush(self):
+        for platform in self.platforms.values():
+            platform.flush()
+
+    def health(self) -> dict[str, Any]:
+        return {
+            platform_name: platform.health().to_dict()
+            for platform_name, platform in self.platforms.items()
+        }
+
+    def get_platform(self, name: str) -> BasePlatform | None:
+        return self.platforms.get(name)

reskpoints/cli.py

@@ -0,0 +1,163 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .agent_logger import AgentLogger
+from .config import AgentLoggerConfig
+
+
+def cmd_log(args):
+    logger = AgentLogger(args.config)
+    params = {}
+    if args.params:
+        params = json.loads(args.params)
+    result = None
+    if args.result:
+        result = json.loads(args.result)
+    results = logger.log(
+        agent_id=args.agent_id,
+        action=args.action,
+        probability=args.probability,
+        params=params,
+        result=result,
+        success=args.success,
+    )
+    print(json.dumps([r.to_dict() for r in results], indent=2))
+    any_fail = any(not r.success for r in results)
+    return 1 if any_fail else 0
+
+
+def cmd_test(args):
+    logger = AgentLogger(args.config)
+    print(f"Testing agent logging on {len(logger.platforms)} platform(s)...")
+    print()
+    for name, platform in logger.platforms.items():
+        entry = _test_entry()
+        result = platform.emit(entry)
+        status = "✓" if result.success else "✗"
+        dur = f"{result.duration_ms:.1f}ms" if result.duration_ms else "?"
+        print(f"  [{status}] {name:15s} {dur:>10s}  {result.error or ''}")
+    print()
+    print("Health:")
+    for pname, h in logger.health().items():
+        print(f"  {pname:15s} status={h['status']} queue={h['queue_size']}")
+    return 0
+
+
+def cmd_status(args):
+    logger = AgentLogger(args.config)
+    print(f"ReskPoints Agent Logger — {logger.environment}")
+    print(f"Host: {logger.host}")
+    print(f"Platforms: {len(logger.platforms)}")
+    print()
+    print(f"{'Platform':<20s} {'Status':<12s} {'Queue':<8s} {'Error':<30s}")
+    print("-" * 70)
+    for pname, h in logger.health().items():
+        print(f"{pname:<20s} {h['status']:<12s} {h['queue_size']:<8d} {h.get('error', '') or '':<30s}")
+    return 0
+
+
+def cmd_tail(args):
+    logger = AgentLogger(args.config)
+    console = logger.get_platform("console")
+    if console is None:
+        print("error: console platform not enabled", file=sys.stderr)
+        return 1
+    print(f"Live tailing logs (Ctrl+C to stop)...")
+    try:
+        import time
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    return 0
+
+
+def cmd_replay(args):
+    path = Path(args.file)
+    if not path.exists():
+        print(f"error: file not found: {args.file}", file=sys.stderr)
+        return 1
+    logger = AgentLogger(args.config)
+    count = 0
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            data = json.loads(line)
+            from .models import ActionLog
+            entry = ActionLog.from_dict(data)
+            logger.log_action(entry)
+            count += 1
+    print(f"Replayed {count} log entries")
+    return 0
+
+
+def _test_entry():
+    from .models import ActionLog
+    return ActionLog(
+        agent_id="test-agent",
+        action="test_action",
+        probability=0.95,
+        parameters={"test": True, "value": 42},
+        result="ok",
+        success=True,
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ReskPoints Agent Action Logger CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--config", "-c",
+        default="reskpoints.yaml",
+        help="Path to config YAML (default: reskpoints.yaml)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command")
+
+    # log
+    log_p = subparsers.add_parser("log", help="Log an agent action")
+    log_p.add_argument("--agent-id", required=True, help="Agent identifier")
+    log_p.add_argument("--action", required=True, help="Action name")
+    log_p.add_argument("--probability", type=float, default=1.0, help="Action probability")
+    log_p.add_argument("--params", help="JSON string of parameters")
+    log_p.add_argument("--result", help="JSON string of result")
+    log_p.add_argument("--success", action="store_true", default=True, help="Success flag")
+
+    # test
+    test_p = subparsers.add_parser("test", help="Test all platforms")
+
+    # status
+    subparsers.add_parser("status", help="Show platform health")
+
+    # tail
+    subparsers.add_parser("tail", help="Live tail logs (console)")
+
+    # replay
+    replay_p = subparsers.add_parser("replay", help="Replay logs from a file")
+    replay_p.add_argument("file", help="Path to JSONL file")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    commands = {
+        "log": cmd_log,
+        "test": cmd_test,
+        "status": cmd_status,
+        "tail": cmd_tail,
+        "replay": cmd_replay,
+    }
+
+    return commands[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

reskpoints/config.py

@@ -0,0 +1,121 @@
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+_ENV_VAR_RE = re.compile(r"\$\{([^}:]+)(?::([^}]*))?\}")
+
+
+def _resolve_env(value: str) -> str:
+    def _replace(m: re.Match) -> str:
+        var = m.group(1)
+        default = m.group(2)
+        return os.environ.get(var, default) if default else os.environ.get(var, "")
+
+    return _ENV_VAR_RE.sub(_replace, value)
+
+
+def _resolve_env_recursive(obj: Any) -> Any:
+    if isinstance(obj, str):
+        return _resolve_env(obj) if "${" in obj else obj
+    if isinstance(obj, dict):
+        return {k: _resolve_env_recursive(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_resolve_env_recursive(v) for v in obj]
+    return obj
+
+
+DEFAULT_CONFIG = {
+    "agent_logger": {
+        "environment": "${ENV:development}",
+        "masking": {
+            "enabled": True,
+            "sensitive_fields": [
+                "api_key",
+                "password",
+                "token",
+                "secret",
+                "authorization",
+            ],
+        },
+        "sampling": {
+            "default_rate": 1.0,
+            "rules": [],
+        },
+        "buffering": {
+            "max_size": 1000,
+            "flush_interval": 5.0,
+        },
+        "retry": {
+            "max_attempts": 3,
+            "backoff": [0.5, 1.5, 4.5],
+            "circuit_breaker": {
+                "threshold": 5,
+                "recovery_time": 30,
+            },
+        },
+        "platforms": {
+            "console": {
+                "enabled": True,
+                "format": "human",
+            },
+        },
+    }
+}
+
+
+class AgentLoggerConfig:
+    def __init__(self, config: dict[str, Any] | None = None):
+        resolved = _resolve_env_recursive(config or {})
+        self._raw = resolved
+
+        section = resolved.get("agent_logger", {})
+        self.environment = section.get("environment", "development")
+        self.masking_config = section.get("masking", {})
+        self.sampling_config = section.get("sampling", {})
+        self.buffering_config = section.get("buffering", {})
+        self.retry_config = section.get("retry", {})
+        self.platforms_config = section.get("platforms", {})
+
+    @property
+    def masking_enabled(self) -> bool:
+        return self.masking_config.get("enabled", True)
+
+    @property
+    def sensitive_fields(self) -> list[str]:
+        return self.masking_config.get("sensitive_fields", [])
+
+    @property
+    def default_rate(self) -> float:
+        return float(self.sampling_config.get("default_rate", 1.0))
+
+    @property
+    def sampling_rules(self) -> list[dict[str, Any]]:
+        return self.sampling_config.get("rules", [])
+
+    def get_sampling_rate(self, action: str) -> float:
+        for rule in self.sampling_rules:
+            pattern = rule.get("action", "")
+            if pattern == action or (pattern.endswith("*") and action.startswith(pattern[:-1])):
+                return float(rule.get("rate", self.default_rate))
+        return self.default_rate
+
+    def get_platform_config(self, name: str) -> dict[str, Any]:
+        return self.platforms_config.get(name, {})
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "AgentLoggerConfig":
+        path = Path(path)
+        if path.exists():
+            with open(path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+        else:
+            data = {}
+        merged = {**DEFAULT_CONFIG, **(data or {})}
+        return cls(merged)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self._raw

reskpoints/decorator.py

@@ -0,0 +1,83 @@
+import functools
+import inspect
+import time
+from typing import Any, Callable, TypeVar
+
+from .agent_logger import AgentLogger
+from .models import ActionLog
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def log_action(
+    agent_id: str | None = None,
+    action_name: str | None = None,
+    logger: AgentLogger | None = None,
+    capture_params: bool = True,
+    capture_result: bool = True,
+    **extra_metadata: Any,
+) -> Callable[[F], F]:
+    def decorator(func: F) -> F:
+        _action_name = action_name or func.__name__
+        module = inspect.getmodule(func)
+        module_name = module.__name__ if module else ""
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            _logger = logger or _get_default_logger()
+            _agent_id = agent_id or _resolve_agent_id(func)
+            t0 = time.time()
+            parameters: dict[str, Any] = {}
+            if capture_params:
+                sig = inspect.signature(func)
+                bound = sig.bind(*args, **kwargs)
+                bound.apply_defaults()
+                parameters = dict(bound.arguments)
+                for k, v in parameters.items():
+                    if hasattr(v, "__dict__"):
+                        parameters[k] = f"<{type(v).__name__}>"
+            try:
+                result = func(*args, **kwargs)
+                duration = (time.time() - t0) * 1000
+                _logger.log(
+                    agent_id=_agent_id,
+                    action=f"{module_name}.{_action_name}",
+                    probability=1.0,
+                    params=parameters,
+                    result=result if capture_result else None,
+                    success=True,
+                    duration_ms=duration,
+                    **extra_metadata,
+                )
+                return result
+            except Exception as e:
+                duration = (time.time() - t0) * 1000
+                _logger.log(
+                    agent_id=_agent_id,
+                    action=f"{module_name}.{_action_name}",
+                    probability=1.0,
+                    params=parameters,
+                    result=str(e),
+                    success=False,
+                    duration_ms=duration,
+                    **extra_metadata,
+                )
+                raise
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+_default_logger: AgentLogger | None = None
+
+
+def _get_default_logger() -> AgentLogger:
+    global _default_logger
+    if _default_logger is None:
+        _default_logger = AgentLogger()
+    return _default_logger
+
+
+def _resolve_agent_id(func: Callable[..., Any]) -> str:
+    return f"{func.__module__}.{func.__qualname__}"

reskpoints/masking.py

@@ -0,0 +1,82 @@
+import re
+from typing import Any
+
+DEFAULT_SENSITIVE_FIELDS = [
+    "api_key",
+    "api_key",
+    "password",
+    "token",
+    "secret",
+    "authorization",
+    "auth_token",
+    "access_token",
+    "refresh_token",
+    "private_key",
+    "session_id",
+]
+
+DEFAULT_PATTERNS: list[tuple[str, str]] = [
+    (r"\b[A-Za-z0-9_\-]{20,}\b", "***"),
+    (r"\b(?:sk-[a-zA-Z0-9]{20,}|pk-[a-zA-Z0-9]{20,})\b", "sk-***"),
+    (r"\b[A-Za-z0-9+/]{40,}(?:=){0,2}\b", "***"),
+]
+
+
+class FieldMasker:
+    def __init__(
+        self,
+        sensitive_fields: list[str] | None = None,
+        patterns: list[tuple[str, str]] | None = None,
+        enabled: bool = True,
+    ):
+        self.sensitive_fields = set(sensitive_fields or DEFAULT_SENSITIVE_FIELDS)
+        self.patterns = [(re.compile(p), m) for p, m in (patterns or DEFAULT_PATTERNS)]
+        self.enabled = enabled
+
+    def mask(self, data: dict[str, Any], extra_fields: list[str] | None = None) -> dict[str, Any]:
+        if not self.enabled:
+            return data
+
+        fields_to_mask = self.sensitive_fields | set(extra_fields or [])
+        result: dict[str, Any] = {}
+
+        for key, value in data.items():
+            if key in fields_to_mask:
+                result[key] = self._mask_value(value)
+            elif isinstance(value, dict):
+                result[key] = self._mask_nested(value, fields_to_mask, depth=0)
+            elif isinstance(value, str):
+                result[key] = self._apply_regex(value)
+            else:
+                result[key] = value
+
+        return result
+
+    def _mask_value(self, value: Any) -> str:
+        s = str(value)
+        if len(s) <= 4:
+            return "****"
+        return s[:2] + "****" + s[-2:] if len(s) > 6 else "****"
+
+    def _mask_nested(
+        self, data: dict[str, Any], fields_to_mask: set[str], depth: int = 0
+    ) -> dict[str, Any]:
+        if depth > 5:
+            return {"_masked": "too_deep"}
+        result: dict[str, Any] = {}
+        for key, value in data.items():
+            if key in fields_to_mask:
+                result[key] = self._mask_value(value)
+            elif isinstance(value, dict):
+                result[key] = self._mask_nested(value, fields_to_mask, depth + 1)
+            elif isinstance(value, str):
+                result[key] = self._apply_regex(value)
+            else:
+                result[key] = value
+        return result
+
+    def _apply_regex(self, value: str) -> str:
+        for pattern, replacement in self.patterns:
+            if pattern.search(value):
+                return pattern.sub(replacement, value)
+        return value