coreiq 0.2.0__tar.gz

coreiq-0.2.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: coreiq
+Version: 0.2.0
+Summary: Production AI middleware with observability dashboard
+Author: CoreIQ Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/coreiq/coreiq
+Project-URL: Documentation, https://coreiq.dev
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: anthropic>=0.28.0
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.7; extra == "embeddings"
+Requires-Dist: numpy>=1.24; extra == "embeddings"
+Provides-Extra: tokenizers
+Requires-Dist: tiktoken>=0.5; extra == "tokenizers"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: tiktoken>=0.7; extra == "dev"

coreiq-0.2.0/coreiq/__init__.py

@@ -0,0 +1,43 @@
+from .client import CoreIQClient, log_event
+from .exceptions import CoreIQError, ValidationError, DatabaseError, ConfigError
+from .evolution.feedback import FeedbackSignal
+from .status import StatusReport
+from .testing import MockCoreIQ, assert_event_logged
+from .security import PromptInjectionError, OutputViolationError
+from .governance import PolicyViolation, ComplianceViolation
+from .performance import BudgetExceeded
+from .tools import ToolSpec, ValidationResult
+from .evolution.sdk import VariantResult
+
+try:
+    from .tracing import trace  # noqa: F401
+    _has_tracing = True
+except ImportError:
+    _has_tracing = False
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "CoreIQClient",
+    "log_event",
+    "CoreIQError",
+    "ValidationError",
+    "DatabaseError",
+    "ConfigError",
+    "FeedbackSignal",
+    "StatusReport",
+    "MockCoreIQ",
+    "assert_event_logged",
+    "PromptInjectionError",
+    "OutputViolationError",
+    "PolicyViolation",
+    "ComplianceViolation",
+    "BudgetExceeded",
+    "ToolSpec",
+    "ValidationResult",
+    "VariantResult",
+]
+
+if _has_tracing:
+    __all__.append("trace")

coreiq-0.2.0/coreiq/client.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional
+
+from .store.writer import get_writer
+
+_logger = logging.getLogger("coreiq")
+
+if TYPE_CHECKING:
+    from .evolution.feedback import FeedbackRecorder
+    from .evolution.sdk import EvolutionSDK
+    from .security.scanner import ScanResult
+    from .performance.budget import BudgetTracker
+    from .performance.cache import InMemorySemanticCache
+    from .performance.router import ModelRouter
+    from .status import StatusReport
+
+Level = Literal["debug", "info", "warning", "error", "critical"]
+_VALID_LEVELS = {"debug", "info", "warning", "error", "critical"}
+_KNOWN_PROVIDERS = {"openai", "anthropic", "vllm", "sglang"}
+
+
+class _ToolsInterface:
+    """Unified interface for tool registration, validation, and routing."""
+
+    def __init__(self, registry, validator, router):
+        self._registry = registry
+        self._validator = validator
+        self._router = router
+
+    def register(self, tools) -> None:
+        self._registry.register(tools)
+
+    def validate(self, tool_name: str, args_json: str):
+        return self._validator.validate(tool_name, args_json)
+
+    def select(self, query: str, top_k: int = 5):
+        return self._router.select(query, top_k)
+
+    def token_savings(self, selected, tokens_per_tool: int = 200) -> int:
+        return self._router.token_savings(selected, tokens_per_tool)
+
+
+class CoreIQClient:
+    def __init__(self, db_path=None, api_key=None, log_level="info", provider="openai", model="gpt-4o"):
+        from .exceptions import ConfigError
+        if provider not in _KNOWN_PROVIDERS:
+            raise ConfigError(f"provider must be one of {sorted(_KNOWN_PROVIDERS)}, got '{provider}'")
+        if log_level not in _VALID_LEVELS:
+            raise ConfigError(f"log_level must be one of {sorted(_VALID_LEVELS)}, got '{log_level}'")
+        self.db_path = db_path
+        self.api_key = api_key
+        self.log_level = log_level
+        self.provider = provider
+        self.model = model
+        self._feedback: FeedbackRecorder | None = None
+        self._evolution: EvolutionSDK | None = None
+        self._tools_registry = None
+        self._tools_validator = None
+        self._tools_router = None
+        self._cache: InMemorySemanticCache | None = None
+        self._budget: BudgetTracker | None = None
+        self._router: ModelRouter | None = None
+
+    def __enter__(self) -> CoreIQClient:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release resources (placeholder for future cleanup)."""
+
+    @property
+    def feedback(self) -> FeedbackRecorder:
+        if self._feedback is None:
+            from .evolution.feedback import get_feedback_recorder
+            self._feedback = get_feedback_recorder()
+        return self._feedback
+
+    @property
+    def evolution(self) -> EvolutionSDK:
+        if self._evolution is None:
+            from .evolution.sdk import EvolutionSDK
+            self._evolution = EvolutionSDK()
+        return self._evolution
+
+    @property
+    def tools(self) -> _ToolsInterface:
+        if self._tools_registry is None:
+            from .tools.registry import ToolRegistry
+            from .tools.validator import ToolValidator
+            from .tools.router import ToolRouter
+            self._tools_registry = ToolRegistry()
+            self._tools_validator = ToolValidator(self._tools_registry)
+            self._tools_router = ToolRouter(self._tools_registry)
+        return _ToolsInterface(self._tools_registry, self._tools_validator, self._tools_router)
+
+    @property
+    def cache(self) -> "InMemorySemanticCache":
+        if self._cache is None:
+            from .performance.cache import InMemorySemanticCache
+            self._cache = InMemorySemanticCache()
+        return self._cache
+
+    def scan(self, messages: list[dict]) -> ScanResult:
+        """Scan messages for injection, PII, and output violations."""
+        from .security.scanner import scan_messages
+        return scan_messages(messages)
+
+    @property
+    def budget(self) -> BudgetTracker:
+        if self._budget is None:
+            from .performance.budget import BudgetTracker, BudgetConfig
+            self._budget = BudgetTracker(BudgetConfig())
+        return self._budget
+
+    @property
+    def router(self) -> ModelRouter:
+        if self._router is None:
+            from .performance.router import ModelRouter
+            self._router = ModelRouter(default_model=self.model)
+        return self._router
+
+    def log_event(
+        self,
+        message: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        *,
+        level: Level = "info",
+        source: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        **extra: Any,
+    ) -> str:
+        """Log a structured event to the CoreIQ store.
+
+        Args:
+            message:  Human-readable description of the event.
+            metadata: Arbitrary key/value pairs attached to the event.
+            level:    Severity — "debug", "info", "warning", "error", "critical".
+            source:   Optional origin label (e.g. module name, agent ID).
+            trace_id: Optionally link this event to an existing trace.
+            **extra:  Extra key/value pairs merged into metadata.
+
+        Returns:
+            The generated event ID (UUID string).
+        """
+        if trace_id is None:
+            from .tracing import get_current_trace_id
+            trace_id = get_current_trace_id()
+        if extra:
+            metadata = {**(metadata or {}), **extra}
+        _validate_level(level)
+        try:
+            return get_writer().insert_event(
+                message=message,
+                metadata=metadata,
+                level=level,
+                source=source,
+                trace_id=trace_id,
+            )
+        except Exception as e:
+            _logger.error("Failed to write event: %s", e)
+            from .exceptions import DatabaseError
+            raise DatabaseError(f"Failed to log event: {e}") from e
+
+    def status(self) -> "StatusReport":
+        """Return a zero-token system health summary (last 7 days).
+
+        Usage::
+
+            status = client.status()
+            print(status)             # human-readable
+            status.to_dict()          # machine-readable
+        """
+        from .status import build_status
+        return build_status()
+
+    def _record_tool_call(
+        self,
+        trace_id: str,
+        tool_name: str,
+        args: Dict[str, Any],
+        valid: bool = True,
+        error: Optional[str] = None,
+    ) -> None:
+        get_writer().insert_tool_call(
+            trace_id=trace_id,
+            tool_name=tool_name,
+            args_json=json.dumps(args),
+            valid=valid,
+            error=error,
+        )
+
+
+def _validate_level(level: str) -> str:
+    if level not in _VALID_LEVELS:
+        from .exceptions import ValidationError
+        raise ValidationError(f"level must be one of {sorted(_VALID_LEVELS)}, got '{level}'")
+    return level
+
+
+def log_event(
+    message: str,
+    metadata: Optional[Dict[str, Any]] = None,
+    *,
+    level: Level = "info",
+    source: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    **extra: Any,
+) -> str:
+    """Module-level convenience wrapper for logging a structured event.
+
+    Usage::
+
+        import coreiq
+        coreiq.log_event("user signed up", {"plan": "pro", "user_id": "u_123"})
+        coreiq.log_event("payment failed", {"amount": 49.99}, level="error")
+        coreiq.log_event("signup", plan="pro", user_id="u1")
+    """
+    if trace_id is None:
+        from .tracing import get_current_trace_id
+        trace_id = get_current_trace_id()
+    if extra:
+        metadata = {**(metadata or {}), **extra}
+    _validate_level(level)
+    try:
+        return get_writer().insert_event(
+            message=message,
+            metadata=metadata,
+            level=level,
+            source=source,
+            trace_id=trace_id,
+        )
+    except Exception as e:
+        _logger.error("Failed to write event: %s", e)
+        from .exceptions import DatabaseError
+        raise DatabaseError(f"Failed to log event: {e}") from e

coreiq-0.2.0/coreiq/config.py

@@ -0,0 +1,45 @@
+"""Central configuration via environment variables."""
+import os
+from pathlib import Path
+
+
+def get_db_path() -> Path:
+    raw = os.environ.get("COREIQ_DB_PATH", "")
+    if raw:
+        return Path(raw)
+    return Path.home() / ".coreiq" / "coreiq.db"
+
+
+def get_api_key() -> str | None:
+    """If set, all /api/* requests must include X-API-Key: <value> header."""
+    return os.environ.get("COREIQ_API_KEY") or None
+
+
+def get_host() -> str:
+    return os.environ.get("COREIQ_HOST", "127.0.0.1")
+
+
+def get_port() -> int:
+    return int(os.environ.get("COREIQ_PORT", "7823"))
+
+
+def get_log_level() -> str:
+    return os.environ.get("COREIQ_LOG_LEVEL", "info").lower()
+
+
+def get_log_json() -> bool:
+    """If true, emit logs as JSON (for structured log aggregators)."""
+    return os.environ.get("COREIQ_LOG_JSON", "").lower() in ("1", "true", "yes")
+
+
+def get_cors_origins() -> list[str]:
+    """Comma-separated allowed CORS origins. Defaults to localhost dev server."""
+    raw = os.environ.get("COREIQ_CORS_ORIGINS", "")
+    if raw:
+        return [o.strip() for o in raw.split(",") if o.strip()]
+    return ["http://localhost:5173"]
+
+
+def get_rate_limit() -> int:
+    """Max requests per minute per IP. 0 = disabled."""
+    return int(os.environ.get("COREIQ_RATE_LIMIT", "0"))

coreiq-0.2.0/coreiq/evolution/__init__.py

@@ -0,0 +1,11 @@
+from .feedback import FeedbackRecorder, get_feedback_recorder
+from .bandit import PromptBandit, Arm
+from .dicl import ExampleStore, Example
+from .finetune import FinetuneDataset, TrainingPair
+
+__all__ = [
+    "FeedbackRecorder", "get_feedback_recorder",
+    "PromptBandit", "Arm",
+    "ExampleStore", "Example",
+    "FinetuneDataset", "TrainingPair",
+]

coreiq-0.2.0/coreiq/evolution/bandit.py

@@ -0,0 +1,84 @@
+"""Multi-armed bandit for prompt variant selection (Thompson sampling)."""
+import random
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Arm:
+    variant_id: str
+    alpha: float = 1.0  # successes + 1 (Beta prior)
+    beta: float = 1.0   # failures + 1 (Beta prior)
+
+    @property
+    def win_rate(self) -> float:
+        return self.alpha / (self.alpha + self.beta)
+
+    @property
+    def samples(self) -> int:
+        return int(self.alpha + self.beta - 2)
+
+    def sample(self) -> float:
+        """Draw from Beta(alpha, beta) — Thompson sampling."""
+        return random.betavariate(self.alpha, self.beta)
+
+    def update(self, reward: float) -> None:
+        """Update with a reward in [0, 1]."""
+        self.alpha += reward
+        self.beta += (1.0 - reward)
+
+
+class PromptBandit:
+    """
+    Thompson-sampling bandit for prompt variant A/B/n testing.
+    Each variant_id maps to a Beta-distribution arm.
+    """
+
+    def __init__(self, variant_ids: list[str]):
+        self._arms: dict[str, Arm] = {vid: Arm(variant_id=vid) for vid in variant_ids}
+
+    def select(self) -> str:
+        """Return the variant_id with the highest Thompson sample."""
+        return max(self._arms.values(), key=lambda a: a.sample()).variant_id
+
+    def reward(self, variant_id: str, value: float) -> None:
+        """Record a reward (0.0–1.0) for a variant."""
+        if variant_id not in self._arms:
+            self._arms[variant_id] = Arm(variant_id=variant_id)
+        self._arms[variant_id].update(max(0.0, min(1.0, value)))
+
+    def add_variant(self, variant_id: str) -> None:
+        if variant_id not in self._arms:
+            self._arms[variant_id] = Arm(variant_id=variant_id)
+
+    def stats(self) -> list[dict]:
+        return [
+            {
+                "variant_id": arm.variant_id,
+                "win_rate": round(arm.win_rate, 4),
+                "samples": arm.samples,
+                "alpha": arm.alpha,
+                "beta": arm.beta,
+            }
+            for arm in sorted(self._arms.values(), key=lambda a: -a.win_rate)
+        ]
+
+    def has_arms(self) -> bool:
+        return bool(self._arms)
+
+    def get_arm(self, variant_id: str) -> Optional[Arm]:
+        return self._arms.get(variant_id)
+
+    def items(self):
+        """Iterate (variant_id, Arm) pairs."""
+        return self._arms.items()
+
+    def restore_arm(self, variant_id: str, alpha: float, beta: float) -> None:
+        """Restore a persisted arm state."""
+        self._arms[variant_id] = Arm(variant_id=variant_id, alpha=alpha, beta=beta)
+
+    def best(self) -> Optional[str]:
+        """Return the variant with the highest current win_rate."""
+        if not self._arms:
+            return None
+        return max(self._arms.values(), key=lambda a: a.win_rate).variant_id

coreiq-0.2.0/coreiq/evolution/dicl.py

@@ -0,0 +1,67 @@
+"""DICL — Dynamic In-Context Learning: select best few-shot examples at runtime."""
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Example:
+    id: str
+    input: str
+    output: str
+    metadata: dict = field(default_factory=dict)
+    score: float = 1.0  # quality/relevance weight
+
+
+class ExampleStore:
+    """In-memory store of labeled examples with cosine-similarity retrieval."""
+
+    def __init__(self):
+        self._examples: list[Example] = []
+
+    def add(self, example: Example) -> None:
+        self._examples.append(example)
+
+    def remove(self, example_id: str) -> bool:
+        before = len(self._examples)
+        self._examples = [e for e in self._examples if e.id != example_id]
+        return len(self._examples) < before
+
+    def retrieve(
+        self,
+        query: str,
+        *,
+        k: int = 3,
+        min_score: float = 0.0,
+    ) -> list[Example]:
+        """
+        Retrieve top-k examples by simple TF-IDF-inspired Jaccard similarity.
+        In production, replace with embedding-based retrieval.
+        """
+        query_tokens = set(query.lower().split())
+        scored: list[tuple[float, Example]] = []
+        for ex in self._examples:
+            if ex.score < min_score:
+                continue
+            ex_tokens = set(ex.input.lower().split())
+            if not query_tokens and not ex_tokens:
+                sim = 1.0
+            elif not query_tokens or not ex_tokens:
+                sim = 0.0
+            else:
+                intersection = query_tokens & ex_tokens
+                union = query_tokens | ex_tokens
+                sim = len(intersection) / len(union)
+            scored.append((sim * ex.score, ex))
+
+        scored.sort(key=lambda x: -x[0])
+        return [ex for _, ex in scored[:k]]
+
+    def to_messages(self, examples: list[Example]) -> list[dict]:
+        """Convert examples to alternating user/assistant message pairs."""
+        messages = []
+        for ex in examples:
+            messages.append({"role": "user", "content": ex.input})
+            messages.append({"role": "assistant", "content": ex.output})
+        return messages
+
+    def __len__(self) -> int:
+        return len(self._examples)

coreiq-0.2.0/coreiq/evolution/feedback.py

@@ -0,0 +1,49 @@
+from enum import Enum
+from typing import Optional
+
+from ..store.writer import get_writer
+
+
+class FeedbackSignal(str, Enum):
+    THUMBS_UP = "thumbs_up"
+    THUMBS_DOWN = "thumbs_down"
+    SCORE = "score"
+    CORRECTION = "correction"
+
+
+class FeedbackRecorder:
+    def record(
+        self,
+        *,
+        response_id: str,
+        signal: str,
+        value: float = 0.0,
+        dimension: Optional[str] = None,
+        correction: Optional[str] = None,
+    ) -> None:
+        get_writer().insert_feedback(
+            response_id=response_id,
+            signal=signal,
+            value=value,
+            dimension=dimension,
+            correction=correction,
+        )
+
+    def thumbs_up(self, response_id: str, dimension: Optional[str] = None) -> None:
+        self.record(response_id=response_id, signal="thumbs_up", value=1.0, dimension=dimension)
+
+    def thumbs_down(self, response_id: str, dimension: Optional[str] = None, correction: Optional[str] = None) -> None:
+        self.record(response_id=response_id, signal="thumbs_down", value=0.0, dimension=dimension, correction=correction)
+
+    def score(self, response_id: str, value: float, dimension: Optional[str] = None) -> None:
+        self.record(response_id=response_id, signal="score", value=value, dimension=dimension)
+
+
+_recorder: Optional[FeedbackRecorder] = None
+
+
+def get_feedback_recorder() -> FeedbackRecorder:
+    global _recorder
+    if _recorder is None:
+        _recorder = FeedbackRecorder()
+    return _recorder

coreiq-0.2.0/coreiq/evolution/finetune.py

@@ -0,0 +1,101 @@
+"""Fine-tune data management — collect, curate, and export training pairs."""
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+
+@dataclass
+class TrainingPair:
+    prompt: str
+    completion: str
+    quality_score: float = 1.0
+    source_trace_id: Optional[str] = None
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    tags: list[str] = field(default_factory=list)
+
+    def to_openai_format(self) -> dict:
+        """Format as OpenAI fine-tuning JSONL record."""
+        return {
+            "messages": [
+                {"role": "user", "content": self.prompt},
+                {"role": "assistant", "content": self.completion},
+            ]
+        }
+
+    def to_alpaca_format(self) -> dict:
+        """Format as Alpaca-style instruction record."""
+        return {
+            "instruction": self.prompt,
+            "input": "",
+            "output": self.completion,
+        }
+
+
+class FinetuneDataset:
+    """Collect and export fine-tuning pairs with quality filtering."""
+
+    def __init__(self, min_quality_score: float = 0.7):
+        self._pairs: list[TrainingPair] = []
+        self._min_quality = min_quality_score
+
+    def add(self, pair: TrainingPair) -> None:
+        self._pairs.append(pair)
+
+    def add_from_feedback(
+        self,
+        prompt: str,
+        completion: str,
+        *,
+        signal: str,
+        value: float = 0.0,
+        correction: Optional[str] = None,
+        trace_id: Optional[str] = None,
+    ) -> Optional[TrainingPair]:
+        """
+        Create a training pair from feedback signal.
+        - thumbs_up: use completion as-is
+        - correction: use correction text as completion
+        - thumbs_down / low score: skip
+        """
+        if signal == "thumbs_up":
+            pair = TrainingPair(prompt=prompt, completion=completion,
+                                quality_score=1.0, source_trace_id=trace_id,
+                                tags=["thumbs_up"])
+        elif signal == "correction" and correction:
+            pair = TrainingPair(prompt=prompt, completion=correction,
+                                quality_score=0.9, source_trace_id=trace_id,
+                                tags=["correction"])
+        elif signal == "score" and value >= self._min_quality:
+            pair = TrainingPair(prompt=prompt, completion=completion,
+                                quality_score=value, source_trace_id=trace_id,
+                                tags=["scored"])
+        else:
+            return None
+        self._pairs.append(pair)
+        return pair
+
+    def export_jsonl(self, path: str, *, fmt: str = "openai", min_score: Optional[float] = None) -> int:
+        """Export to JSONL file. Returns number of records written."""
+        threshold = min_score if min_score is not None else self._min_quality
+        pairs = [p for p in self._pairs if p.quality_score >= threshold]
+        with open(path, "w") as f:
+            for pair in pairs:
+                record = pair.to_openai_format() if fmt == "openai" else pair.to_alpaca_format()
+                f.write(json.dumps(record) + "\n")
+        return len(pairs)
+
+    def __len__(self) -> int:
+        return len(self._pairs)
+
+    @property
+    def stats(self) -> dict:
+        if not self._pairs:
+            return {"total": 0, "avg_quality": 0.0, "ready": 0}
+        avg_q = sum(p.quality_score for p in self._pairs) / len(self._pairs)
+        ready = sum(1 for p in self._pairs if p.quality_score >= self._min_quality)
+        return {
+            "total": len(self._pairs),
+            "avg_quality": round(avg_q, 3),
+            "ready": ready,
+        }