krysta 1.0.5__tar.gz

krysta-1.0.5/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: krysta
+Version: 1.0.5
+Summary: A unified multimodal model evaluation tracking and engineering report engine.
+Author: Anshu Aditya
+Project-URL: Homepage, https://github.com/your-username/kwing_library
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: httpx-sse>=0.4.0
+
+# NoA Python SDK API Reference Documentation
+
+This document provides technical reference details for the classes, methods, parameters, and streaming response objects available within the `krysta` client library.
+
+---
+
+## Core Class Architecture
+
+### `NoA` Class
+The main client manager used to initialize connections and manage state lifecycle pipes with your remote execution infrastructure gateway.
+
+```python
+from krysta.noa import Noa
+```
+
+#### Class Constructor Matrix
+```python
+Noa(gateway_url: str)
+```
+* **Parameters:**
+  * `gateway_url` *(str, Required)*: The base HTTP/WS network address of your running NoA server cluster dashboard node (e.g., `"http://localhost:3000"`).
+
+#### Context Manager Methods
+The client class fully implements the standard asynchronous context manager layout (`__aenter__` / `__aexit__`) to automatically handle socket connections, channel allocations, and memory resource cleanups safely.
+
+```python
+async with Noa(gateway_url="...") as client:
+    # Execution resources are automatically allocated here
+    pass
+# Connection pipes are safely destroyed here
+```
+
+---
+
+## Method Reference Maps
+
+### `execute()`
+Initiates an asynchronous Server-Sent Events (SSE) background task worker thread to evaluate a raw source code string.
+
+#### Method Definition Syntax
+```python
+def execute(
+    language: str, 
+    code: str, 
+    timeout_ms: int = 5000
+) -> AsyncIterator[dict]:
+```
+
+#### Input Arguments Block
+* **`language`** *(str, Required)*: The programming compilation runner target environment to spawn inside the isolated cluster node. Supported strings:
+  * `"python"`
+  * `"javascript"`
+* **`code`** *(str, Required)*: The uncompiled text string payload containing the raw source code script to evaluate inside the container pool.
+* **`timeout_ms`** *(int, Optional)*: The strict maximum allowed execution time window in milliseconds before the watchdog thread hard-kills (`SIGKILL`) the task runner. Default fallback threshold value: `5000`.
+
+#### Return Type Value
+* Returns an **`AsyncIterator[dict]`** stream generator object. You must consume this data payload frame-by-frame using an `async for` loop layout block.
+
+---
+
+## Stream Event Response Payload Schema
+
+Every data unit emitted from the async iterator returns a structured Python `dict` map object containing the following token parameters:
+
+```json
+{
+  "type": "system" | "stdout" | "stderr" | "rules" | "done" | "error",
+  "text": string | null,
+  "timestamp": integer
+}
+```
+
+### Event Parameter Types Definition Matrix
+
+#### 1. `type: "system"`
+Emitted immediately when the gateway server begins allocating memory allocations or scheduling task execution queues.
+* **Text Contents:** Standard tracking message flags (e.g., `"EXECUTION_STARTED"`).
+
+#### 2. `type: "stdout"`
+Emitted instantly whenever the sandboxed script writes characters to the standard console system output.
+* **Text Contents:** The raw printed string text data.
+
+#### 3. `type: "stderr"`
+Emitted instantly when unhandled runtime errors, system exceptions, or line code tracebacks occur inside the isolated runner.
+* **Text Contents:** Standard multiline traceback exception information text.
+
+#### 4. `type: "rules"`
+Emitted near task termination. Contains a serialized JSON string listing static metric quality scores and evaluation check markers.
+* **Text Contents Schema:**
+  ```json
+  "[{\"rule\": \"ExitCodeZeroRule\", \"result\": \"PASS\" | \"FAIL\", \"reason\": \"...\"}]"
+  ```
+
+#### 5. `type: "done"`
+Emitted when the execution lifecycle pipeline completes its loop naturally and closes down successfully.
+* **Text Contents:** `null`
+
+#### 6. `type: "error"`
+Emitted if a network drop occurs, or if the server cannot complete an internal spawn routing operation.
+* **Text Contents:** Detailed platform failure tracking notes (e.g., `"Job failed during execution"`).

krysta-1.0.5/README.md

@@ -0,0 +1,100 @@
+# NoA Python SDK API Reference Documentation
+
+This document provides technical reference details for the classes, methods, parameters, and streaming response objects available within the `krysta` client library.
+
+---
+
+## Core Class Architecture
+
+### `NoA` Class
+The main client manager used to initialize connections and manage state lifecycle pipes with your remote execution infrastructure gateway.
+
+```python
+from krysta.noa import Noa
+```
+
+#### Class Constructor Matrix
+```python
+Noa(gateway_url: str)
+```
+* **Parameters:**
+  * `gateway_url` *(str, Required)*: The base HTTP/WS network address of your running NoA server cluster dashboard node (e.g., `"http://localhost:3000"`).
+
+#### Context Manager Methods
+The client class fully implements the standard asynchronous context manager layout (`__aenter__` / `__aexit__`) to automatically handle socket connections, channel allocations, and memory resource cleanups safely.
+
+```python
+async with Noa(gateway_url="...") as client:
+    # Execution resources are automatically allocated here
+    pass
+# Connection pipes are safely destroyed here
+```
+
+---
+
+## Method Reference Maps
+
+### `execute()`
+Initiates an asynchronous Server-Sent Events (SSE) background task worker thread to evaluate a raw source code string.
+
+#### Method Definition Syntax
+```python
+def execute(
+    language: str, 
+    code: str, 
+    timeout_ms: int = 5000
+) -> AsyncIterator[dict]:
+```
+
+#### Input Arguments Block
+* **`language`** *(str, Required)*: The programming compilation runner target environment to spawn inside the isolated cluster node. Supported strings:
+  * `"python"`
+  * `"javascript"`
+* **`code`** *(str, Required)*: The uncompiled text string payload containing the raw source code script to evaluate inside the container pool.
+* **`timeout_ms`** *(int, Optional)*: The strict maximum allowed execution time window in milliseconds before the watchdog thread hard-kills (`SIGKILL`) the task runner. Default fallback threshold value: `5000`.
+
+#### Return Type Value
+* Returns an **`AsyncIterator[dict]`** stream generator object. You must consume this data payload frame-by-frame using an `async for` loop layout block.
+
+---
+
+## Stream Event Response Payload Schema
+
+Every data unit emitted from the async iterator returns a structured Python `dict` map object containing the following token parameters:
+
+```json
+{
+  "type": "system" | "stdout" | "stderr" | "rules" | "done" | "error",
+  "text": string | null,
+  "timestamp": integer
+}
+```
+
+### Event Parameter Types Definition Matrix
+
+#### 1. `type: "system"`
+Emitted immediately when the gateway server begins allocating memory allocations or scheduling task execution queues.
+* **Text Contents:** Standard tracking message flags (e.g., `"EXECUTION_STARTED"`).
+
+#### 2. `type: "stdout"`
+Emitted instantly whenever the sandboxed script writes characters to the standard console system output.
+* **Text Contents:** The raw printed string text data.
+
+#### 3. `type: "stderr"`
+Emitted instantly when unhandled runtime errors, system exceptions, or line code tracebacks occur inside the isolated runner.
+* **Text Contents:** Standard multiline traceback exception information text.
+
+#### 4. `type: "rules"`
+Emitted near task termination. Contains a serialized JSON string listing static metric quality scores and evaluation check markers.
+* **Text Contents Schema:**
+  ```json
+  "[{\"rule\": \"ExitCodeZeroRule\", \"result\": \"PASS\" | \"FAIL\", \"reason\": \"...\"}]"
+  ```
+
+#### 5. `type: "done"`
+Emitted when the execution lifecycle pipeline completes its loop naturally and closes down successfully.
+* **Text Contents:** `null`
+
+#### 6. `type: "error"`
+Emitted if a network drop occurs, or if the server cannot complete an internal spawn routing operation.
+* **Text Contents:** Detailed platform failure tracking notes (e.g., `"Job failed during execution"`).

krysta-1.0.5/krysta/__init__.py

@@ -0,0 +1,111 @@
+import json
+import httpx
+import asyncio
+from typing import AsyncGenerator
+from .trace import ExecutionTrace
+from .sandbox import RuleEngine
+
+class Noa:
+    """The primary public entrypoint for the Krysta NoA SDK ecosystem."""
+    def __init__(self, gateway_url: str = "http://localhost:3000" or "https://kwing.vercel.app/submit/api/submit"):
+        self.gateway_url = gateway_url
+        self._engine = RuleEngine()
+
+    def spawn(self, language: str, code: str):
+        return NoaExecutionLifecycle(self.gateway_url, language, code)
+
+    def trace(self, job_id: str) -> ExecutionTrace:
+        """
+        Fetches the final ExecutionTrace for a completed job from Redis.
+        """
+        return ExecutionTrace.from_redis(job_id)
+
+    def validate(self, trace: ExecutionTrace) -> dict:
+        """
+        Passes an ExecutionTrace through the sandbox RuleEngine validator.
+        """
+        return self._engine.validate(trace)
+
+    async def execute(self, language: str, code: str) -> ExecutionTrace:
+        """
+        High-level orchestration method that automatically posts a job, consumes
+        and exhausts the live streaming frames, and resolves into a full ExecutionTrace.
+        """
+        lifecycle = self.spawn(language, code)
+
+        try:
+            async with lifecycle as stream:
+                async for _ in stream:
+                    # Consume all frames including metrics — lifecycle stores them internally
+                    pass
+        except httpx.ReadError:
+            print(f"\n[SDK WARNING] Telemetry pipe disrupted or closed early by server.")
+
+        job_id = lifecycle.job_id
+
+        if job_id:
+            print(f"[SDK INFO] Fetching final validation metric traces for Job ID: {job_id}...")
+            # FIX: call self.trace() which delegates to ExecutionTrace.from_redis()
+            trace = self.trace(job_id)
+
+            # FIX: backfill duration_ms from the metrics frame captured during streaming
+            if lifecycle.duration_ms is not None:
+                trace.duration_ms = lifecycle.duration_ms
+
+            return trace
+        else:
+            raise RuntimeError("[SDK ERROR] Connection dropped before a Job ID could be securely assigned.")
+
+
+class NoaExecutionLifecycle:
+    """Handles the inner stateful scope of an active streaming execution task connection."""
+    def __init__(self, gateway_url: str, language: str, code: str):
+        self.gateway_url = gateway_url
+        self.language = language
+        self.code = code
+        self.job_id = None
+        self.duration_ms = None  # FIX: capture metrics frame duration here
+
+    async def __aenter__(self):
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.gateway_url}/api/submit",
+                json={"language": self.language, "code": self.code}
+            )
+            response.raise_for_status()
+            payload = response.json()
+            self.job_id = payload.get("jobId")
+
+        return self._stream_generator()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+    async def _stream_generator(self) -> AsyncGenerator[dict, None]:
+        async with httpx.AsyncClient(timeout=None) as client:
+            async with client.stream("GET", f"{self.gateway_url}/api/stream?jobId={self.job_id}") as response:
+                print("[SDK DEBUG] SSE Stream link connected! Awaiting incoming frames from background worker...")
+                async for line in response.aiter_lines():
+                    if line.startswith("data:"):
+                        try:
+                            frame = json.loads(line[5:])
+                            print(f"[SDK DEBUG] Received frame type: {frame.get('type')}")
+
+                            # FIX: capture duration_ms from metrics frame before yielding
+                            if frame.get("type") == "metrics" and frame.get("text"):
+                                try:
+                                    metrics = json.loads(frame["text"])
+                                    self.duration_ms = metrics.get("duration_ms", 0)
+                                except Exception as e:
+                                    print(f"[SDK WARNING] Failed to parse metrics frame: {e}")
+
+                            yield frame
+
+                            if frame.get("type") in ["done", "timeout", "error"]:
+                                print("[SDK DEBUG] Terminal lifecycle frame detected. Closing stream context connection.")
+                                break
+                        except Exception as e:
+                            print(f"[SDK DEBUG] Failed to parse frame line: {e}")
+                            continue
+
+                        

krysta-1.0.5/krysta/noa.py

@@ -0,0 +1,84 @@
+import httpx
+from httpx_sse import aconnect_sse
+import asyncio
+from typing import AsyncIterator, Optional
+
+class Noa:
+    def __init__(self, gateway_url: str = "http://localhost:3000"):
+        """
+        Initializes the Krysta Sandbox execution engine SDK client interface.
+        """
+        self.gateway_url = gateway_url.rstrip("/")
+        self.client: Optional[httpx.AsyncClient] = None
+
+    async def __aenter__(self):
+        # Open an asynchronous persistent HTTP connection pool block
+        self.client = httpx.AsyncClient()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # Cleanly sever pool allocation on block departure
+        if self.client:
+            await self.client.aclose()
+
+    async def execute(self, language: str, code: str, timeout_ms: int = 10000) -> AsyncIterator[dict]:
+        """
+        POSTs the code execution task to the API gateway, then establishes 
+        an SSE live event connection to stream runtime events chunk-by-chunk.
+        """
+        if not self.client:
+            raise RuntimeError("Noa context manager must be entered using 'async with Noa(...) as noa:'")
+
+        submit_url = f"{self.gateway_url}/api/submit"
+        stream_url = f"{self.gateway_url}/api/stream"
+
+        payload = {
+            "language": language,
+            "code": code,
+            "timeout_ms": timeout_ms
+        }
+
+        # 1. Dispatch code payload out to ingestion gateway
+        response = await self.client.post(submit_url, json=payload)
+        
+        # Enhanced debugging check to catch blank or failed gateway hits
+        if response.status_code != 202:
+            raise RuntimeError(
+                f"Gateway Rejected Request.\n"
+                f"Status Code: {response.status_code}\n"
+                f"Raw Response Content: '{response.text}'"
+            )
+
+        try:
+            receipt = response.json()
+        except Exception as json_err:
+            raise RuntimeError(
+                f"Gateway returned non-JSON response.\n"
+                f"Status Code: {response.status_code}\n"
+                f"Raw Response Content: '{response.text}'"
+            )
+
+        job_id = receipt.get("jobId")
+        
+        if not job_id:
+            raise ValueError(f"Gateway failed to yield a valid infrastructure jobId transaction receipt token.")
+
+        # 2. Bind directly to the live event telemetry stream bus
+        params = {"jobId": job_id}
+        
+        print(f"[SDK DEBUG] Establishing SSE streaming pipe connection to {stream_url}...")
+        
+        try:
+            # Pass an explicit, prolonged timeout configuration payload to prevent httpx from dropping early
+            timeout_config = httpx.Timeout(60.0, connect=10.0)
+            
+            async with aconnect_sse(self.client, "GET", stream_url, params=params, timeout=timeout_config) as event_stream:
+                print("[SDK DEBUG] SSE pipe connection link established. Awaiting daemon frames...")
+                async for event in event_stream.aiter_sse():
+                    # Yield decoded structured events out to user tracking script loops
+                    yield event.json()
+                    
+        except httpx.TimeoutException as timeout_err:
+            raise RuntimeError(f"Streaming telemetry channel timed out waiting for broker response. Details: {timeout_err}")
+        except Exception as stream_err:
+            raise RuntimeError(f"SSE Telemetry transport layer connection failed. Details: ({type(stream_err).__name__}) {stream_err}")

krysta-1.0.5/krysta/sandbox.py

@@ -0,0 +1,84 @@
+import json
+from typing import Tuple, Dict
+from .trace import ExecutionTrace
+
+class ValidationRule:
+    """Abstract base class for all sandbox evaluation rules."""
+    def evaluate(self, trace: ExecutionTrace) -> Tuple[bool, str]:
+        raise NotImplementedError
+
+
+class ExitCodeZeroRule(ValidationRule):
+    """Verifies that the sandboxed process wrapped up operations with a clean exit status."""
+    def evaluate(self, trace: ExecutionTrace) -> Tuple[bool, str]:
+        if trace.timeout_hit:
+            return False, "Sandbox execution exceeded the allocated runtime wall clock limit."
+        if trace.exit_code is None:
+            return False, "Process terminated abruptly without returning a valid exit status code."
+        if trace.exit_code != 0:
+            return False, f"Process terminated with unhandled non-zero exit status: {trace.exit_code}."
+        return True, "Process completed runtime operations cleanly with exit code 0."
+
+
+class ValidJsonRule(ValidationRule):
+    """Ensures the console stdout stream can be compiled into structured JSON metadata."""
+    def evaluate(self, trace: ExecutionTrace) -> Tuple[bool, str]:
+        # Collect and concatenate all stdout text chunks
+        combined_output = "".join([
+            line.get("text", "") 
+            for line in trace.stdout_lines 
+            if line.get("type") == "stdout"
+        ])
+        
+        # Strip out system lifecycle banners injected by the daemon infrastructure
+        clean_payload = combined_output.replace("SYSTEM // EXECUTION_STARTED", "").strip()
+        
+        if not clean_payload:
+            return False, "Process stdout stream is completely empty. No data payload found to parse."
+        
+        try:
+            json.loads(clean_payload)
+            return True, "Stdout stream successfully compiled into valid structural JSON."
+        except json.JSONDecodeError as e:
+            return False, f"Malformed output layout. Failed to parse stream as structural JSON. Details: {str(e)}"
+
+
+class NoNetworkCallsRule(ValidationRule):
+    """Inspects log traces to detect unauthorized outbound socket connection attempts."""
+    def evaluate(self, trace: ExecutionTrace) -> Tuple[bool, str]:
+        # Check standard low-level connection trace patterns and error string indicators
+        for frame in trace.stdout_lines:
+            text = frame.get("text", "").lower()
+            if any(marker in text for marker in ["socket", "http", "connection refused", "urllib", "requests"]):
+                return False, f"Security sandbox violation: Rogue external network handshake detected: '{frame.get('text')}'"
+        return True, "No outbound socket or data link requests detected during script lifecycle tracking."
+
+
+class RuleEngine:
+    """Orchestrates sequential trace assessments against the configured ruleset profile."""
+    def __init__(self):
+        self.rules = [
+            ExitCodeZeroRule(),
+            ValidJsonRule(),
+            NoNetworkCallsRule()
+        ]
+
+    def validate(self, trace: ExecutionTrace) -> Dict[str, any]:
+        results = {}
+        overall_passed = True
+        
+        for rule in self.rules:
+            rule_name = rule.__class__.__name__
+            passed, reason = rule.evaluate(trace)
+            if not passed:
+                overall_passed = False
+            
+            results[rule_name] = {
+                "status": "PASS" if passed else "FAIL",
+                "reason": reason
+            }
+            
+        return {
+            "passed": overall_passed,
+            "results": results
+        }

krysta-1.0.5/krysta/trace.py

@@ -0,0 +1,74 @@
+import json
+import os
+from dotenv import load_dotenv
+from upstash_redis import Redis
+from typing import List, Dict, Optional
+
+load_dotenv(dotenv_path=".env.local")
+
+class ExecutionTrace:
+    def __init__(
+        self,
+        job_id: str,
+        duration_ms: int = 0,
+        stdout_lines: List[Dict] = None,
+        exit_code: int = None,
+        timeout_hit: bool = False
+    ):
+        self.job_id = job_id
+        self.duration_ms = duration_ms
+        self.stdout_lines = stdout_lines or []
+        self.exit_code = exit_code
+        self.timeout_hit = timeout_hit
+
+    @classmethod
+    def from_redis(cls, job_id: str):
+        """
+        Connects to Upstash Redis via REST API, inspects the execution status,
+        and maps the execution trace.
+        """
+        redis_url = os.getenv("UPSTASH_REDIS_REST_URL")
+        redis_token = os.getenv("UPSTASH_REDIS_REST_TOKEN")
+
+        if not redis_url:
+            raise ValueError("[TRACE] Missing UPSTASH_REDIS_REST_URL environment variable.")
+        if not redis_token:
+            raise ValueError("[TRACE] Missing UPSTASH_REDIS_REST_TOKEN environment variable.")
+
+        # ✅ Use Upstash REST client — no TCP/TLS port issues
+        client = Redis(url=redis_url, token=redis_token)
+
+        # Read the lifecycle state directly from the status key
+        status = client.get(f"status:{job_id}") or "unknown"
+        
+        raw_lines = client.lrange(f"stdout:{job_id}", 0, -1) or []
+        stdout_lines = [{"type": "stdout", "text": line.strip()} for line in raw_lines]
+
+        duration_ms = 0
+        timeout_hit = (status == "timeout")
+
+        if status == "done":
+            exit_code = 0
+        elif status == "error":
+            exit_code = 1
+        elif status == "timeout":
+            exit_code = None
+        else:
+            exit_code = None
+
+        return cls(
+            job_id=job_id,
+            duration_ms=duration_ms,
+            stdout_lines=stdout_lines,
+            exit_code=exit_code,
+            timeout_hit=timeout_hit
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "jobId": self.job_id,
+            "duration_ms": self.duration_ms,
+            "stdout_lines": self.stdout_lines,
+            "exit_code": self.exit_code,
+            "timeout_hit": self.timeout_hit
+        }

krysta-1.0.5/krysta.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: krysta
+Version: 1.0.5
+Summary: A unified multimodal model evaluation tracking and engineering report engine.
+Author: Anshu Aditya
+Project-URL: Homepage, https://github.com/your-username/kwing_library
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: httpx-sse>=0.4.0
+
+# NoA Python SDK API Reference Documentation
+
+This document provides technical reference details for the classes, methods, parameters, and streaming response objects available within the `krysta` client library.
+
+---
+
+## Core Class Architecture
+
+### `NoA` Class
+The main client manager used to initialize connections and manage state lifecycle pipes with your remote execution infrastructure gateway.
+
+```python
+from krysta.noa import Noa
+```
+
+#### Class Constructor Matrix
+```python
+Noa(gateway_url: str)
+```
+* **Parameters:**
+  * `gateway_url` *(str, Required)*: The base HTTP/WS network address of your running NoA server cluster dashboard node (e.g., `"http://localhost:3000"`).
+
+#### Context Manager Methods
+The client class fully implements the standard asynchronous context manager layout (`__aenter__` / `__aexit__`) to automatically handle socket connections, channel allocations, and memory resource cleanups safely.
+
+```python
+async with Noa(gateway_url="...") as client:
+    # Execution resources are automatically allocated here
+    pass
+# Connection pipes are safely destroyed here
+```
+
+---
+
+## Method Reference Maps
+
+### `execute()`
+Initiates an asynchronous Server-Sent Events (SSE) background task worker thread to evaluate a raw source code string.
+
+#### Method Definition Syntax
+```python
+def execute(
+    language: str, 
+    code: str, 
+    timeout_ms: int = 5000
+) -> AsyncIterator[dict]:
+```
+
+#### Input Arguments Block
+* **`language`** *(str, Required)*: The programming compilation runner target environment to spawn inside the isolated cluster node. Supported strings:
+  * `"python"`
+  * `"javascript"`
+* **`code`** *(str, Required)*: The uncompiled text string payload containing the raw source code script to evaluate inside the container pool.
+* **`timeout_ms`** *(int, Optional)*: The strict maximum allowed execution time window in milliseconds before the watchdog thread hard-kills (`SIGKILL`) the task runner. Default fallback threshold value: `5000`.
+
+#### Return Type Value
+* Returns an **`AsyncIterator[dict]`** stream generator object. You must consume this data payload frame-by-frame using an `async for` loop layout block.
+
+---
+
+## Stream Event Response Payload Schema
+
+Every data unit emitted from the async iterator returns a structured Python `dict` map object containing the following token parameters:
+
+```json
+{
+  "type": "system" | "stdout" | "stderr" | "rules" | "done" | "error",
+  "text": string | null,
+  "timestamp": integer
+}
+```
+
+### Event Parameter Types Definition Matrix
+
+#### 1. `type: "system"`
+Emitted immediately when the gateway server begins allocating memory allocations or scheduling task execution queues.
+* **Text Contents:** Standard tracking message flags (e.g., `"EXECUTION_STARTED"`).
+
+#### 2. `type: "stdout"`
+Emitted instantly whenever the sandboxed script writes characters to the standard console system output.
+* **Text Contents:** The raw printed string text data.
+
+#### 3. `type: "stderr"`
+Emitted instantly when unhandled runtime errors, system exceptions, or line code tracebacks occur inside the isolated runner.
+* **Text Contents:** Standard multiline traceback exception information text.
+
+#### 4. `type: "rules"`
+Emitted near task termination. Contains a serialized JSON string listing static metric quality scores and evaluation check markers.
+* **Text Contents Schema:**
+  ```json
+  "[{\"rule\": \"ExitCodeZeroRule\", \"result\": \"PASS\" | \"FAIL\", \"reason\": \"...\"}]"
+  ```
+
+#### 5. `type: "done"`
+Emitted when the execution lifecycle pipeline completes its loop naturally and closes down successfully.
+* **Text Contents:** `null`
+
+#### 6. `type: "error"`
+Emitted if a network drop occurs, or if the server cannot complete an internal spawn routing operation.
+* **Text Contents:** Detailed platform failure tracking notes (e.g., `"Job failed during execution"`).

krysta-1.0.5/krysta.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+krysta/__init__.py
+krysta/noa.py
+krysta/sandbox.py
+krysta/trace.py
+krysta.egg-info/PKG-INFO
+krysta.egg-info/SOURCES.txt
+krysta.egg-info/dependency_links.txt
+krysta.egg-info/requires.txt
+krysta.egg-info/top_level.txt
+krysta_reporter/__init__.py
+krysta_reporter/dispatch.py
+krysta_reporter/engine.py
+krysta_reporter/templates/base_report.md

krysta-1.0.5/krysta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

krysta-1.0.5/krysta.egg-info/requires.txt

@@ -0,0 +1,6 @@
+jinja2>=3.0.0
+matplotlib>=3.5.0
+numpy>=1.20.0
+pyyaml>=6.0
+httpx>=0.27.0
+httpx-sse>=0.4.0

krysta-1.0.5/krysta.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+krysta
+krysta_reporter

krysta-1.0.5/krysta_reporter/__init__.py

@@ -0,0 +1 @@
+from .engine import ModelReport

krysta-1.0.5/krysta_reporter/engine.py

@@ -0,0 +1,317 @@
+import os
+from datetime import datetime
+from jinja2 import Template
+import yaml
+import time
+
+class ModelReport:
+    def __init__(self, week: int, model_name: str, modality: str):
+        self.week = week
+        self.model_name = model_name
+        self.modality = modality
+        self.artifact_counter = 0
+        
+        # Core data metrics trackers
+        self.timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+        self.metrics = {} 
+        
+        # 1. Load configuration profiles safely
+        self.config = self._load_global_config()
+        
+        # 2. Extract workspace paths from config or default back to standard pathways
+        base_workspace = self.config.get("workspace_root", "workspace_reports")
+        self.output_dir = os.path.join(base_workspace, "2026", f"week-{week}_{model_name}")
+        self.report_dir = self.output_dir  # Add this line to fix the final compile directory lookup
+        self.artifacts_dir = os.path.join(self.output_dir, "artifacts")
+        
+        os.makedirs(self.artifacts_dir, exist_ok=True)
+        
+    def _load_global_config(self):
+        """Looks for a local kwing_config.yaml file in the user's working directory."""
+        config_filename = "kwing_config.yaml"
+        default_config = {
+            "workspace_root": "workspace_reports",
+            "thresholds": {
+                "token_confidence": 0.50,
+                "vram_limit_mb": 4000.0,
+                "latency_limit_ms": 100.0
+            }
+        }
+        
+        if os.path.exists(config_filename):
+            try:
+                with open(config_filename, "r") as f:
+                    user_config = yaml.safe_load(f)
+                    if user_config:
+                        # Clean, industrial CLI layout
+                        print("[INFO] krysta-wing :: loaded runtime profile from kwing_config.yaml")
+                        return user_config
+            except Exception as e:
+                print(f"[WARN] krysta-wing :: configuration parsing failed ({e}). using defaults.")
+                
+        return default_config
+
+    def log_benchmarks(self, latency: float, vram: float, loss: float):
+        """Logs standard performance engineering parameters."""
+        self.metrics["latency"] = latency
+        self.metrics["vram"] = vram
+        self.metrics["loss"] = round(loss, 4)
+
+    def log_vision_artifact(self, image_matrix, title: str = "Model Attention Heatmap"):
+        """Captures a visual matrix, names it uniquely, and saves it to disk."""
+        from .modalities.vision import save_analysis_plot
+
+        self.artifact_counter += 1
+        filename = f"artifact_{self.artifact_counter}.png"
+        target_path = os.path.join(self.artifacts_dir, filename)
+
+        
+        save_analysis_plot(image_matrix, target_path, title)
+
+    
+        relative_markdown_path = f"artifacts/{filename}"
+        self.logged_artifacts.append((title, relative_markdown_path))
+
+        print(f"[✓] Visual artifact saved to: {target_path}")
+
+    def log_text_artifact(self, tokens: list, confidences: list, sample_phrase: str, threshold: float = 0.5):
+        """Processes NLP evaluation data and catches text extraction anomalies."""
+        from .modalities.text import analyze_token_confidence
+        
+        
+        low_conf_words = analyze_token_confidence(tokens, confidences, threshold)
+        
+        
+        text_summary = f"#### Evaluated Sequence Sample:\n`\"{sample_phrase}\"`\n\n"
+        if low_conf_words:
+            text_summary += f"⚠️ **Low Confidence Anomaly Tokens (Below {int(threshold*100)}%):**\n"
+            text_summary += f"{', '.join(low_conf_words)}\n"
+        else:
+            text_summary += "✓ **All tokens parsed with high confidence spectral safety.**\n"
+            
+        
+        if not hasattr(self, 'logged_text_blocks'):
+            self.logged_text_blocks = []
+        self.logged_text_blocks.append(text_summary)
+        
+        print(f"[✓] Text analysis artifact logged for sequence.")
+
+    def log_audio_artifact(self, raw_audio_array, title: str = "Audio Mel-Spectrogram"):
+        """Processes raw audio data arrays, converts to a spectrogram, and logs the path."""
+        from .modalities.audio import save_spectrogram_plot
+        
+        self.artifact_counter += 1
+        filename = f"audio_artifact_{self.artifact_counter}.png"
+        target_path = os.path.join(self.artifacts_dir, filename)
+        
+        
+        save_spectrogram_plot(raw_audio_array, target_path, title)
+        
+        
+        relative_markdown_path = f"artifacts/{filename}"
+        if not hasattr(self, 'logged_artifacts'):
+            self.logged_artifacts = []
+        self.logged_artifacts.append((title, relative_markdown_path))
+        
+        print(f"[✓] Audio spectrogram artifact saved to: {target_path}")
+
+    def log_custom_artifact(self, data, artifact_type: str, title: str, **kwargs):
+        """
+        Universal gateway method making the architecture model-agnostic.
+        Routes data dynamically to modality processors based on the artifact_type string.
+        
+        Supported types: 'heatmap' (Vision Matrix), 'tokens' (NLP Sequences), 'audio' (Waveform Signals)
+        """
+        self.artifact_counter += 1
+        
+        if not hasattr(self, 'logged_artifacts'):
+            self.logged_artifacts = []
+        if not hasattr(self, 'logged_text_blocks'):
+            self.logged_text_blocks = []
+
+        # Route 1: Vision / Spatial Heatmaps
+        if artifact_type == "heatmap":
+            # Updated to match your exact file function name: save_analysis_plot
+            from .modalities.vision import save_analysis_plot
+            filename = f"custom_vision_{self.artifact_counter}.png"
+            target_path = os.path.join(self.artifacts_dir, filename)
+            save_analysis_plot(data, target_path, title)
+            self.logged_artifacts.append((title, f"artifacts/{filename}"))
+            print(f"[CORE] krysta-wing :: registered vision artifact ↳ {filename}")
+
+        # Route 2: Text Token Streams
+        elif artifact_type == "tokens":
+            # Updated to match your exact file function name: analyze_token_confidence
+            from .modalities.text import analyze_token_confidence
+            confidences = kwargs.get("confidences", [])
+            sample_phrase = kwargs.get("sample_phrase", "Raw Token String Segment Passed")
+
+            config_threshold = self.config.get("thresholds", {}).get("token_confidence", 0.50)
+            threshold = kwargs.get("threshold", config_threshold)
+            
+            low_conf_words = analyze_token_confidence(data, confidences, threshold)
+            
+            text_summary = f"#### Custom Token Stream Analysis: {title}\n"
+            text_summary += f"`\"{sample_phrase}\"`\n\n"
+            if low_conf_words:
+                text_summary += f"**Low Confidence Anomaly Tokens (Below {int(threshold*100)}%):**\n"
+                text_summary += f"{', '.join(low_conf_words)}\n\n"
+            else:
+                text_summary += "**All tokens parsed securely above target boundary criteria.**\n\n"
+            
+            self.logged_text_blocks.append(text_summary)
+            print(f"[CORE] krysta-wing :: registered text token anomalies")
+
+        
+        elif artifact_type == "audio":
+            from .modalities.audio import save_spectrogram_plot
+            filename = f"custom_audio_{self.artifact_counter}.png"
+            target_path = os.path.join(self.artifacts_dir, filename)
+            save_spectrogram_plot(data, target_path, title)
+            self.logged_artifacts.append((title, f"artifacts/{filename}"))
+            print(f"[✓] Model-Agnostic Engine: Logged Audio Spectrogram -> {filename}")
+
+        else:
+            raise ValueError(f"Unsupported artifact type variant: '{artifact_type}'. Choose 'heatmap', 'tokens', or 'audio'.")
+
+    def compile(self):
+        """Reads template, hydrates variables, and exports the final file."""
+    
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        template_path = os.path.join(current_dir, "templates", "base_report.md")
+
+        # Run statistical anomaly checks before rendering the template
+        alerts = self._compute_regression_analysis()
+        alert_markdown_block = ""
+        if alerts:
+            alert_markdown_block = (
+                "### RUNTIME TELEMETRY ANOMALIES\n"
+                "> **NOTICE:** The statistical tracking engine flagged performance metrics "
+                "exceeding expected variance limits against historical baselines.\n>\n"
+            )
+            for alert in alerts:
+                # Remove emojis from individual alert strings if you have them inside _compute_regression_analysis
+                alert_markdown_block += f"> * {alert.replace('⚠️ ', '').replace('🚨 ', '')}\n"
+            alert_markdown_block += "\n---\n"
+        
+        with open(template_path, "r") as f:
+            raw_template = f.read()
+            
+        
+        template = Template(raw_template)
+        
+        
+        # Build dynamic markdown blocks tracking ALL custom-logged entries
+        modality_content = "SYSTEM INTERPRETABILITY & MULTI-MODAL ARTIFACTS\n\n"
+        has_content = False
+
+        
+        if hasattr(self, 'logged_artifacts') and self.logged_artifacts:
+            has_content = True
+            for title, path in self.logged_artifacts:
+                modality_content += f"#### {title}\n![{title}]({path})\n\n"
+
+        
+        if hasattr(self, 'logged_text_blocks') and self.logged_text_blocks:
+            has_content = True
+            for block in self.logged_text_blocks:
+                modality_content += block
+
+        if not has_content:
+            modality_content += "*No evaluation artifacts or modality streams logged during this operational execution pass.*"
+        
+        
+        rendered_md = template.render(
+            model_name=self.model_name,
+            week=self.week,
+            timestamp=self.timestamp,
+            modality=self.modality,
+            latency=self.metrics.get("latency", 0.0),
+            vram=self.metrics.get("vram", 0.0),
+            loss=self.metrics.get("loss", 0.0),
+            modality_specific_content=modality_content,
+            regression_alerts=alert_markdown_block
+            
+        )
+        
+        
+        output_file_path = os.path.join(self.report_dir, "report.md")
+        with open(output_file_path, "w", encoding="utf-8") as f:
+            f.write(rendered_md)
+            
+        print(f"[SUCCESS] krysta-wing :: consolidated report exported to {output_file_path}")
+
+    def _compute_regression_analysis(self):
+        """
+        Saves run metrics locally and runs a 2-sigma anomaly verification pass 
+        against historical evaluation baselines.
+        """
+        import json
+        history_file = ".kwing_history.json"
+        
+        # Pull current performance parameters cleanly
+        current_latency = self.metrics.get("latency", 0.0)
+        current_vram = self.metrics.get("vram", 0.0)
+        
+        # Load historical benchmarks state
+        history_data = []
+        if os.path.exists(history_file):
+            try:
+                with open(history_file, "r") as f:
+                    history_data = json.load(f)
+            except Exception:
+                history_data = []
+
+        regression_alerts = []
+
+        # Run statistical checks only if we have a viable baseline (minimum 3 historical runs)
+        if len(history_data) >= 3:
+            import math
+            
+            latencies = [run["latency"] for run in history_data if "latency" in run]
+            vrams = [run["vram"] for run in history_data if "vram" in run]
+            
+            def calculate_stats(data_list):
+                mean = sum(data_list) / len(data_list)
+                variance = sum((x - mean) ** 2 for x in data_list) / len(data_list)
+                std_dev = math.sqrt(variance)
+                return mean, std_dev
+
+            # Check 1: Latency Regression Spike Checks
+            if latencies:
+                mean_lat, std_lat = calculate_stats(latencies)
+                # If standard deviation is near zero, protect against false positives by setting a minimum window
+                threshold_lat = mean_lat + max(2 * std_lat, 5.0) 
+                if current_latency > threshold_lat:
+                    regression_alerts.append(
+                        f"⚠️ **PERFORMANCE REGRESSION:** Inference Latency spiked to **{current_latency:.1f}ms** "
+                        f"(Historical Baseline: {mean_lat:.1f}ms ± {std_lat:.1f}ms). Exceeded 2σ limit threshold."
+                    )
+
+            # Check 2: Graphics Memory Allocation Checks
+            if vrams:
+                mean_vram, std_vram = calculate_stats(vrams)
+                threshold_vram = mean_vram + max(2 * std_vram, 256.0)
+                if current_vram > threshold_vram:
+                    regression_alerts.append(
+                        f"⚠️ **RESOURCE ANOMALY:** Peak VRAM consumption reached **{current_vram:.1f}MB** "
+                        f"(Historical Baseline: {mean_vram:.1f}MB ± {std_vram:.1f}MB). Potential memory leak detected."
+                    )
+
+        # Append the current profile parameters safely to history logs
+        history_data.append({
+            "timestamp": self.timestamp,
+            "model_name": self.model_name,
+            "week": self.week,
+            "latency": current_latency,
+            "vram": current_vram,
+            "loss": self.metrics.get("loss", 0.0)
+        })
+
+        try:
+            with open(history_file, "w") as f:
+                json.dump(history_data, f, indent=4)
+        except Exception as e:
+            print(f"⚠️ Warning: Unable to save runtime profile data to history store ({e})")
+
+        return regression_alerts

krysta-1.0.5/krysta_reporter/templates/base_report.md

@@ -0,0 +1,29 @@
+# KRYSTA WING // MODEL BENCHMARK REPORT
+
+## METADATA PROFILE
+* **Identifier:** {{ model_name }}
+* **Evaluation Window:** Week {{ week }}
+* **Timestamp:** {{ timestamp }}
+* **Active Modality:** {{ modality | upper }}
+
+---
+
+## 1.0 COMPUTE & PERFORMANCE METRICS
+
+| Evaluation Parameter | Operational Value | Status / Threshold |
+| :--- | :--- | :--- |
+| **Inference Latency** | {{ latency }} ms / sample | {% if latency < 50 %}NOMINAL{% else %}ATTENTION REQUIRED{% endif %} |
+| **Peak VRAM Allocation** | {{ vram }} MB | COMPLIANT |
+| **Target Loss Metrics** | {{ loss }} | RECORDED |
+
+{{ regression_alerts }}
+
+---
+
+## 2.0 MULTI-MODAL INTERPRETABILITY ARTIFACTS
+{{ modality_specific_content }}
+
+---
+
+## 3.0 AUTOMATED EXECUTION SUMMARY
+> **System Verdict:** Runtime evaluation pipeline executed completely. Performance parameters and logged interpretation states have been successfully archived in the target workspace directory.

krysta-1.0.5/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "krysta"
+version = "1.0.5"
+authors = [
+    { name = "Anshu Aditya" }
+]
+description = "A unified multimodal model evaluation tracking and engineering report engine."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "jinja2>=3.0.0",
+    "matplotlib>=3.5.0",
+    "numpy>=1.20.0",
+    "pyyaml>=6.0",
+    "httpx>=0.27.0",
+    "httpx-sse>=0.4.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/your-username/kwing_library"
+
+[tool.setuptools]
+packages = ["krysta_reporter", "krysta"]
+
+[tool.setuptools.package-data]
+"krysta_reporter" = ["templates/*.md"]

krysta-1.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+