xoras-agent-framework 2.0.0__py3-none-any.whl

build/lib/build/lib/examples/01_basic_agent.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""
+XORAS Agentic Framework — Basic Agent Example
+Demonstrates environment initialization, tool execution, and signed trace receipts.
+"""
+
+from xoras import XORASAgentEnvironment
+
+def main():
+    print("=== XORAS Agent Framework — Basic Agent Example ===")
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+
+    # Execute a safe file write tool
+    result = env.execute_tool(
+        agent_name="Engineer",
+        tool_name="file_write",
+        args={
+            "path": "artifacts/basic_agent_output.json",
+            "content": '{"message": "Hello from XORAS Agent Framework v2.0", "status": "active"}'
+        }
+    )
+
+    print("\nExecution Result:")
+    print("Success:", result.get("success"))
+    print("Path:", result.get("path"))
+    print("Receipt Signature:", result.get("receipt_signature"))
+
+if __name__ == "__main__":
+    main()

build/lib/build/lib/examples/02_secure_code_evaluator.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+XORAS Agentic Framework — AST Code Security Evaluator
+Demonstrates AST static analysis and rejection of unsafe dynamic code snippets.
+"""
+
+from xoras import ASTSecurityEngine
+
+def evaluate_snippets():
+    engine = ASTSecurityEngine()
+    
+    snippets = [
+        ("Safe Data Handler", "def process(x):\n    return x.strip().lower()\n"),
+        ("Dynamic Eval Snippet", "eval('import os; os.system(\"ls\")')\n"),
+        ("Unsafe Subprocess", "import subprocess\nsubprocess.Popen('rm -rf /tmp', shell=True)\n"),
+        ("Hardcoded API Key", "AWS_SECRET_ACCESS_KEY = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'\n")
+    ]
+
+    print("=== XORAS AST Security Evaluator Demo ===")
+    for title, code in snippets:
+        res = engine.scan_code(code)
+        print(f"\n[Snippet]: {title}")
+        print(f"Status: {'SAFE [PASSED]' if res.is_safe else 'UNSAFE [REJECTED]'}")
+        print(f"Safety Score: {res.safety_score * 100:.1f}%")
+        if res.violations:
+            print("Violations:", res.violations)
+        if res.secrets_detected:
+            print("Secrets:", res.secrets_detected)
+
+if __name__ == "__main__":
+    evaluate_snippets()

build/lib/build/lib/tests/test_ast_security.py

@@ -0,0 +1,47 @@
+"""
+Unit tests for XORAS AST Security Engine.
+"""
+
+import pytest
+from xoras.ast_security import ASTSecurityEngine
+
+def test_ast_safe_code():
+    engine = ASTSecurityEngine()
+    code = """
+def calculate_sum(a, b):
+    return a + b
+
+print(calculate_sum(10, 20))
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is True
+    assert result.safety_score == 1.0
+    assert len(result.violations) == 0
+
+def test_ast_forbidden_eval():
+    engine = ASTSecurityEngine()
+    code = """
+x = 10
+eval("print(x)")
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert any("eval()" in v for v in result.violations)
+
+def test_ast_forbidden_exec():
+    engine = ASTSecurityEngine()
+    code = """
+exec("import os; os.system('ls')")
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert any("exec()" in v for v in result.violations)
+
+def test_ast_secret_leak_detection():
+    engine = ASTSecurityEngine()
+    code = """
+AWS_SECRET_ACCESS_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert len(result.secrets_detected) > 0

build/lib/build/lib/tests/test_runtime.py

@@ -0,0 +1,42 @@
+"""
+Unit tests for XORAS Agentic Runtime & Orchestrator.
+"""
+
+import os
+from xoras.runtime import XORASAgentEnvironment
+from xoras.orchestrator import SwarmOrchestrator
+
+def test_runtime_file_write_and_read():
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+    write_res = env.execute_tool("Engineer", "file_write", {
+        "path": "artifacts/test_artifact.json",
+        "content": '{"version": "2.0.0", "status": "active"}'
+    })
+    assert write_res["success"] is True
+    assert "receipt_signature" in write_res
+
+    read_res = env.execute_tool("Engineer", "file_read", {
+        "path": "artifacts/test_artifact.json"
+    })
+    assert read_res["success"] is True
+    assert "active" in read_res["content"]
+
+def test_runtime_ast_rejection():
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+    unsafe_res = env.execute_tool("Engineer", "file_write", {
+        "path": "artifacts/bad.py",
+        "content": 'eval("print(\'unsafe\')")'
+    })
+    assert unsafe_res["success"] is False
+    assert "blocked by XORAS AST security" in unsafe_res["error"]
+
+def test_swarm_orchestrator_pipeline():
+    orch = SwarmOrchestrator()
+    res = orch.run_pipeline(
+        task_description="Deploy secure configuration manifest",
+        code_payload='{"config": "valid_json"}',
+        target_path="artifacts/swarm_output.json"
+    )
+    assert res["success"] is True
+    assert res["stage"] == "COMPLETED"
+    assert res["safety_score"] == 1.0

build/lib/build/lib/tests/test_signer.py

@@ -0,0 +1,27 @@
+"""
+Unit tests for XORAS Cryptographic Signer.
+"""
+
+from xoras.signer import CryptographicSigner
+
+def test_evidence_receipt_signing_and_verification():
+    signer = CryptographicSigner()
+    payload = {"path": "test.txt", "content": "hello world"}
+    receipt = signer.sign_receipt("Engineer", "file_write", payload, "SUCCESS")
+    
+    assert receipt.version == "xoras.evidence.v1"
+    assert receipt.organization == "XORAS Systems LLC"
+    assert receipt.status == "SUCCESS"
+    assert receipt.signature is not None
+    
+    # Verify signature mathematically
+    assert signer.verify_receipt(receipt) is True
+
+def test_evidence_receipt_tamper_rejection():
+    signer = CryptographicSigner()
+    payload = {"path": "test.txt", "content": "hello world"}
+    receipt = signer.sign_receipt("Engineer", "file_write", payload, "SUCCESS")
+    
+    # Tamper with status
+    receipt.status = "FAILED"
+    assert signer.verify_receipt(receipt) is False

build/lib/build/lib/xoras/__init__.py

@@ -0,0 +1,23 @@
+"""
+XORAS Systems LLC — Agentic Environment & Governance Framework
+Enterprise-grade multi-agent runtime, AST static security gating, and cryptographic provenance receipts.
+"""
+
+__version__ = "2.0.0"
+__author__ = "XORAS Systems LLC"
+
+from .config import XORASConfig
+from .ast_security import ASTSecurityEngine, ASTScanResult
+from .signer import CryptographicSigner, EvidenceReceipt
+from .runtime import XORASAgentEnvironment
+from .orchestrator import SwarmOrchestrator
+
+__all__ = [
+    "XORASConfig",
+    "ASTSecurityEngine",
+    "ASTScanResult",
+    "CryptographicSigner",
+    "EvidenceReceipt",
+    "XORASAgentEnvironment",
+    "SwarmOrchestrator",
+]

build/lib/build/lib/xoras/ast_security.py

@@ -0,0 +1,141 @@
+"""
+XORAS Systems LLC — AST Security Engine & Secret Scanner
+Performs strict Abstract Syntax Tree (AST) static analysis and entropy secret detection.
+"""
+
+import ast
+import re
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+@dataclass
+class ASTScanResult:
+    is_safe: bool
+    violations: List[str] = field(default_factory=list)
+    secrets_detected: List[str] = field(default_factory=list)
+    safety_score: float = 1.0
+    nodes_analyzed: int = 0
+
+class ASTSecurityVisitor(ast.NodeVisitor):
+    def __init__(self):
+        self.violations: List[str] = []
+        self.nodes_analyzed: int = 0
+        
+        # Unsafe call names
+        self.forbidden_calls = {
+            "eval": "Dynamic evaluation via eval() is strictly prohibited by XORAS AST Guardrails.",
+            "exec": "Dynamic execution via exec() is strictly prohibited by XORAS AST Guardrails.",
+            "compile": "Dynamic compilation via compile() is prohibited in agent runtime.",
+            "__import__": "Dynamic import via __import__ is prohibited.",
+        }
+        
+        # Unsafe module imports
+        self.dangerous_modules = {
+            "ctypes": "Raw memory manipulation via ctypes is restricted.",
+            "pty": "Pseudo-terminal creation via pty is prohibited.",
+            "code": "Interactive interpreter via code module is restricted."
+        }
+
+    def visit(self, node):
+        self.nodes_analyzed += 1
+        super().visit(node)
+
+    def visit_Call(self, node):
+        # Inspect function call names
+        func_name = None
+        if isinstance(node.func, ast.Name):
+            func_name = node.func.id
+        elif isinstance(node.func, ast.Attribute):
+            func_name = node.func.attr
+            
+        if func_name in self.forbidden_calls:
+            self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.forbidden_calls[func_name]}")
+            
+        # Check os.system / subprocess.Popen with unsafe args
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            module_name = node.func.value.id
+            if module_name == "os" and func_name in ("system", "popen", "execv", "execl"):
+                # Inspect string argument if available
+                if node.args and isinstance(node.args[0], ast.Constant):
+                    arg_val = str(node.args[0].value)
+                    if "rm -rf" in arg_val or "sudo " in arg_val or "> /dev/" in arg_val:
+                        self.violations.append(f"Line {getattr(node, 'lineno', '?')}: High-risk shell command in os.{func_name}: '{arg_val}'")
+            elif module_name == "subprocess" and func_name in ("Popen", "call", "run"):
+                # Check shell=True kwargs
+                for keyword in node.keywords:
+                    if keyword.arg == "shell" and isinstance(keyword.value, ast.Constant) and keyword.value.value is True:
+                        self.violations.append(f"Line {getattr(node, 'lineno', '?')}: Subprocess invocation with shell=True is restricted under XORAS AST policy.")
+
+        self.generic_visit(node)
+
+    def visit_Import(self, node):
+        for alias in node.names:
+            if alias.name in self.dangerous_modules:
+                self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.dangerous_modules[alias.name]}")
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node):
+        if node.module in self.dangerous_modules:
+            self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.dangerous_modules[node.module]}")
+        self.generic_visit(node)
+
+
+class ASTSecurityEngine:
+    SECRET_PATTERNS = [
+        (r'(?i)(?:aws_access_key_id|aws_secret_access_key|api_key|secret_key|private_key)\s*[:=]\s*["\']([^"\']{8,})["\']', "Hardcoded API / Secret Key"),
+        (r'AKIA[0-9A-Z]{16}', "AWS Access Key ID"),
+        (r'sk_live_[0-9a-zA-Z]{24,}', "Stripe Live API Key"),
+        (r'sk-(?:proj-)?[a-zA-Z0-9_-]{32,}', "OpenAI API Key"),
+        (r'sk-ant-[a-zA-Z0-9_-]{32,}', "Anthropic API Key"),
+        (r'AIzaSy[0-9a-zA-Z_-]{33}', "Google Gemini API Key"),
+        (r'xox[baprs]-[0-9a-zA-Z]{10,48}', "Slack OAuth / Bot Token"),
+        (r'ghp_[0-9a-zA-Z]{36}', "GitHub Personal Access Token"),
+        (r'-----BEGIN\s+(?:RSA|EC|OPENSSH|PRIVATE)\s+KEY-----', "Private Cryptographic Key Block"),
+    ]
+
+    def __init__(self, strict_mode: bool = True):
+        self.strict_mode = strict_mode
+
+    def scan_code(self, code_snippet: str) -> ASTScanResult:
+        """Parses python AST syntax tree and runs regex secret scanning."""
+        violations: List[str] = []
+        secrets_detected: List[str] = []
+        
+        # 1. Secret scanning across raw code
+        for pattern, desc in self.SECRET_PATTERNS:
+            matches = re.findall(pattern, code_snippet)
+            if matches:
+                secrets_detected.append(f"Secret Leak Warning: Detected {desc} pattern in code payload.")
+                violations.append(f"Secret Scanner: High-entropy token matching '{desc}' found.")
+
+        # 2. Syntax validation & AST parsing
+        nodes_analyzed = 0
+        try:
+            tree = ast.parse(code_snippet)
+            visitor = ASTSecurityVisitor()
+            visitor.visit(tree)
+            violations.extend(visitor.violations)
+            nodes_analyzed = visitor.nodes_analyzed
+        except SyntaxError as e:
+            # If not python syntax (e.g. bash script), fallback to regex heuristic scanner
+            nodes_analyzed = len(code_snippet.splitlines())
+            forbidden_heuristics = [
+                (r'\beval\s*\(', "Dynamic eval() invocation"),
+                (r'\bexec\s*\(', "Dynamic exec() invocation"),
+                (r'rm\s+-rf\s+/', "Destructive root filesystem command 'rm -rf /'"),
+                (r':\(\)\{\s*:\|:&\s*\};:', "Fork bomb pattern"),
+            ]
+            for pat, msg in forbidden_heuristics:
+                if re.search(pat, code_snippet):
+                    violations.append(f"Heuristic AST Fallback Violation: Detected forbidden pattern '{msg}'")
+
+        is_safe = len(violations) == 0
+        safety_score = max(0.0, 1.0 - (len(violations) * 0.35))
+        
+        return ASTScanResult(
+            is_safe=is_safe,
+            violations=violations,
+            secrets_detected=secrets_detected,
+            safety_score=round(safety_score, 4),
+            nodes_analyzed=nodes_analyzed
+        )

build/lib/build/lib/xoras/cli.py

@@ -0,0 +1,211 @@
+"""
+XORAS Systems LLC — CLI Tooling Entrypoint (xoras-cli)
+Command line interface for initializing environments, running AST security scans, and serving web dashboards.
+"""
+
+import argparse
+import json
+import os
+import sys
+import http.server
+import socketserver
+import webbrowser
+from typing import List
+
+from .config import XORASConfig
+from .ast_security import ASTSecurityEngine
+from .runtime import XORASAgentEnvironment
+from .orchestrator import SwarmOrchestrator
+
+DEFAULT_RULES = """# XORAS SYSTEMS LLC — AGENTIC ENVIRONMENT & GOVERNANCE SPECIFICATION
+
+[AGENT_IDENTITY]
+Entity: XORAS Autonomous Agent Node
+Architecture: Multi-Agent Orchestrator (XORAS Swarm)
+Governance Policy: Strict Execution Guardrails & AST Safety Verification
+
+[OPERATIONAL_DIRECTIVES]
+1. AUTONOMOUS_EXECUTION: Resolve intent via iterative state evaluation, tool invocation, and self-correction prior to human escalation.
+2. AST_SECURITY_GATING: All dynamic code execution, subprocess calls, and external payloads must pass AST static analysis and secret scanning (`env-integrity-sentry`).
+3. ZERO_DRIFT_BRANDING: Enforce XORAS Systems LLC branding across all client-facing artifacts, logs, and generated assets. Legacy naming is prohibited.
+4. DETERMINISTIC_LOGGING: Every agent state transition, tool call, and FFI interaction must produce structured JSON-L traces.
+"""
+
+DEFAULT_ENV_YAML = """version: "2.0.0"
+organization: "XORAS Systems LLC"
+runtime:
+  environment_type: "agentic-sandbox"
+  concurrency_limit: 8
+  default_timeout_seconds: 120
+  memory_limit_mb: 4096
+
+security:
+  ast_verification: true
+  allow_network_egress: true
+  allowed_domains:
+    - "github.com"
+    - "pypi.org"
+  secret_scanner: "env-integrity-sentry"
+  block_deprecated_branding: true
+
+agent_swarm:
+  orchestrator:
+    model: "gemini-2.5-flash"
+    temperature: 0.1
+    max_tokens: 8192
+  agents:
+    - name: "Architect"
+      role: "System design, specification authoring, and state graph planning"
+      capabilities: ["file_read", "file_write", "diagram_gen"]
+    - name: "Engineer"
+      role: "Code generation, refactoring, and AST verification"
+      capabilities: ["file_read", "file_write", "bash_exec", "test_runner"]
+    - name: "Auditor"
+      role: "Security scanning, secret detection, and runtime compliance"
+      capabilities: ["ast_scan", "log_audit", "policy_check"]
+
+paths:
+  workspace_root: "."
+  log_output: "./logs/xoras_agent_traces.jsonl"
+  artifact_store: "./artifacts"
+"""
+
+def init_cmd():
+    print("[XORAS CLI] Initializing XORAS Agentic Governance Environment...")
+    if not os.path.exists(".xorasrules"):
+        with open(".xorasrules", "w", encoding="utf-8") as f:
+            f.write(DEFAULT_RULES)
+        print(" -> Created .xorasrules")
+    else:
+        print(" -> .xorasrules already exists.")
+
+    if not os.path.exists("xoras.env.yaml"):
+        with open("xoras.env.yaml", "w", encoding="utf-8") as f:
+            f.write(DEFAULT_ENV_YAML)
+        print(" -> Created xoras.env.yaml")
+    else:
+        print(" -> xoras.env.yaml already exists.")
+        
+    os.makedirs("logs", exist_ok=True)
+    os.makedirs("artifacts", exist_ok=True)
+    print("[XORAS CLI] Initialization complete. Your workspace is secured with XORAS AST Guardrails.")
+
+def scan_cmd(target_file: str):
+    print(f"[XORAS CLI] Running AST Security Scan on target: '{target_file}'")
+    if not os.path.exists(target_file):
+        print(f"Error: Target file or directory '{target_file}' not found.")
+        sys.exit(1)
+        
+    files_to_scan: List[str] = []
+    if os.path.isdir(target_file):
+        for root, _, files in os.walk(target_file):
+            for file in files:
+                if file.endswith(".py"):
+                    files_to_scan.append(os.path.join(root, file))
+    else:
+        files_to_scan.append(target_file)
+
+    engine = ASTSecurityEngine()
+    total_violations = 0
+    total_secrets = 0
+    any_failed = False
+
+    for file_path in files_to_scan:
+        with open(file_path, "r", encoding="utf-8") as f:
+            code = f.read()
+
+        result = engine.scan_code(code)
+        print(f"\n--- AST SCAN REPORT: {file_path} ---")
+        print(f"Status: {'PASSED [SAFE]' if result.is_safe else 'REJECTED [UNSAFE]'}")
+        print(f"Safety Score: {result.safety_score * 100:.1f}% | AST Nodes Analyzed: {result.nodes_analyzed}")
+
+        if result.violations:
+            total_violations += len(result.violations)
+            print("Violations Detected:")
+            for v in result.violations:
+                print(f" - {v}")
+
+        if result.secrets_detected:
+            total_secrets += len(result.secrets_detected)
+            print("Secret Leaks Detected:")
+            for s in result.secrets_detected:
+                print(f" - {s}")
+
+        if not result.is_safe:
+            any_failed = True
+
+    print(f"\n[XORAS CLI Summary] Scanned {len(files_to_scan)} file(s). Total Violations: {total_violations} | Total Secret Warnings: {total_secrets}")
+    if any_failed:
+        sys.exit(2)
+
+def run_cmd(target_file: str):
+    print(f"[XORAS CLI] Executing script '{target_file}' under XORAS Sandboxed Runtime...")
+    if not os.path.exists(target_file):
+        print(f"Error: Target file '{target_file}' not found.")
+        sys.exit(1)
+        
+    with open(target_file, "r", encoding="utf-8") as f:
+        code = f.read()
+
+    env = XORASAgentEnvironment()
+    res = env.execute_tool("Engineer", "bash_exec", {"command": f"{sys.executable} {target_file}"})
+    
+    print("\n--- EXECUTION OUTPUT ---")
+    print(res.get("stdout", ""))
+    if res.get("stderr"):
+        print("STDERR:", res.get("stderr"))
+    print(f"Exit Code: {res.get('exit_code', -1)}")
+    print(f"Trace Receipt Signature: {res.get('receipt_signature', 'NONE')}")
+
+def serve_cmd(port: int = 8080):
+    web_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "web")
+    if not os.path.exists(web_dir):
+        web_dir = os.path.join(os.getcwd(), "web")
+
+    if not os.path.exists(web_dir):
+        print(f"Error: Web dashboard directory '{web_dir}' not found.")
+        sys.exit(1)
+
+    os.chdir(web_dir)
+    Handler = http.server.SimpleHTTPRequestHandler
+    print(f"[XORAS CLI] Serving Web Product Page & Live Dashboard at http://localhost:{port}")
+    try:
+        with socketserver.TCPServer(("", port), Handler) as httpd:
+            print(f"[XORAS CLI] Server running. Press Ctrl+C to stop.")
+            httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[XORAS CLI] Server stopped.")
+
+def main():
+    parser = argparse.ArgumentParser(description="XORAS Systems LLC — Agentic Framework CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # init command
+    init_p = subparsers.add_parser("init", help="Initialize .xorasrules and xoras.env.yaml in current workspace")
+
+    # scan command
+    scan_p = subparsers.add_parser("scan", help="Run AST security and secret scan on a script")
+    scan_p.add_argument("file", help="Python or shell script to scan")
+
+    # run command
+    run_p = subparsers.add_parser("run", help="Run a script through XORAS agentic runtime")
+    run_p.add_argument("file", help="Python script to run")
+
+    # serve command
+    serve_p = subparsers.add_parser("serve", help="Serve interactive product landing page and dashboard")
+    serve_p.add_argument("--port", type=int, default=8080, help="Port to serve on (default: 8080)")
+
+    args = parser.parse_args()
+    if args.command == "init":
+        init_cmd()
+    elif args.command == "scan":
+        scan_cmd(args.file)
+    elif args.command == "run":
+        run_cmd(args.file)
+    elif args.command == "serve":
+        serve_cmd(args.port)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

build/lib/build/lib/xoras/config.py

@@ -0,0 +1,102 @@
+"""
+XORAS Systems LLC — Configuration Schema Parser & Validator
+Loads and validates xoras.env.yaml runtime configurations.
+"""
+
+import os
+import yaml
+from dataclasses import dataclass, field
+from typing import Dict, Any, List, Optional
+
+@dataclass
+class RuntimeConfig:
+    environment_type: str = "agentic-sandbox"
+    concurrency_limit: int = 8
+    default_timeout_seconds: int = 120
+    memory_limit_mb: int = 4096
+
+@dataclass
+class SecurityConfig:
+    ast_verification: bool = True
+    allow_network_egress: bool = True
+    allowed_domains: List[str] = field(default_factory=lambda: ["github.com", "pypi.org"])
+    secret_scanner: str = "env-integrity-sentry"
+    block_deprecated_branding: bool = True
+
+@dataclass
+class AgentSpec:
+    name: str
+    role: str
+    capabilities: List[str]
+
+@dataclass
+class AgentSwarmConfig:
+    orchestrator_model: str = "gemini-2.5-flash"
+    temperature: float = 0.1
+    max_tokens: int = 8192
+    agents: List[AgentSpec] = field(default_factory=list)
+
+@dataclass
+class XORASConfig:
+    version: str
+    organization: str
+    runtime: RuntimeConfig
+    security: SecurityConfig
+    swarm: AgentSwarmConfig
+    workspace_root: str
+    log_output: str
+    artifact_store: str
+
+    @classmethod
+    def load_from_yaml(cls, filepath: str = "xoras.env.yaml") -> "XORASConfig":
+        if not os.path.exists(filepath):
+            raise FileNotFoundError(f"XORAS environment configuration not found at '{filepath}'")
+
+        with open(filepath, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+
+        rt_data = raw.get("runtime", {})
+        runtime_cfg = RuntimeConfig(
+            environment_type=rt_data.get("environment_type", "agentic-sandbox"),
+            concurrency_limit=rt_data.get("concurrency_limit", 8),
+            default_timeout_seconds=rt_data.get("default_timeout_seconds", 120),
+            memory_limit_mb=rt_data.get("memory_limit_mb", 4096)
+        )
+
+        sec_data = raw.get("security", {})
+        security_cfg = SecurityConfig(
+            ast_verification=sec_data.get("ast_verification", True),
+            allow_network_egress=sec_data.get("allow_network_egress", True),
+            allowed_domains=sec_data.get("allowed_domains", ["github.com", "pypi.org"]),
+            secret_scanner=sec_data.get("secret_scanner", "env-integrity-sentry"),
+            block_deprecated_branding=sec_data.get("block_deprecated_branding", True)
+        )
+
+        swarm_raw = raw.get("agent_swarm", {})
+        orch_raw = swarm_raw.get("orchestrator", {})
+        agent_specs = []
+        for a in swarm_raw.get("agents", []):
+            agent_specs.append(AgentSpec(
+                name=a.get("name", "Agent"),
+                role=a.get("role", "Worker"),
+                capabilities=a.get("capabilities", [])
+            ))
+
+        swarm_cfg = AgentSwarmConfig(
+            orchestrator_model=orch_raw.get("model", "gemini-2.5-flash"),
+            temperature=orch_raw.get("temperature", 0.1),
+            max_tokens=orch_raw.get("max_tokens", 8192),
+            agents=agent_specs
+        )
+
+        paths = raw.get("paths", {})
+        return cls(
+            version=raw.get("version", "2.0.0"),
+            organization=raw.get("organization", "XORAS Systems LLC"),
+            runtime=runtime_cfg,
+            security=security_cfg,
+            swarm=swarm_cfg,
+            workspace_root=paths.get("workspace_root", "."),
+            log_output=paths.get("log_output", "./logs/xoras_agent_traces.jsonl"),
+            artifact_store=paths.get("artifact_store", "./artifacts")
+        )