holoscript 1.0.0__tar.gz

holoscript-1.0.0/.gitignore

@@ -0,0 +1,47 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Test coverage
+coverage/
+
+# AI Workspace (Proprietary Research)
+.ai-workspace/
+
+# Proprietary Training Data
+*.jsonl
+training_audit.csv
+synthetic_*.txt
+scripts/data/
+scripts/*synthetic*.py
+scripts/*train*.py
+scripts/inference_test.py
+scripts/debug_gen.py
+
+# Package manager
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

holoscript-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: holoscript
+Version: 1.0.0
+Summary: Python bindings for HoloScript - VR scene description language
+Project-URL: Homepage, https://holoscript.dev
+Project-URL: Documentation, https://holoscript.dev/python
+Project-URL: Repository, https://github.com/brianonbased-dev/Holoscript
+Project-URL: Issues, https://github.com/brianonbased-dev/Holoscript/issues
+Author-email: Brian X Base Team <team@holoscript.dev>
+License-Expression: MIT
+Keywords: 3d,ar,holoscript,metaverse,scene-description,vr,xr
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: pyodide
+Description-Content-Type: text/markdown
+
+# HoloScript Python Bindings
+
+Python bindings for HoloScript - parse, validate, and generate HoloScript code from Python.
+
+## Installation
+
+```bash
+pip install holoscript
+```
+
+## Quick Start
+
+```python
+from holoscript import HoloScript, parse, validate, generate
+
+# Initialize
+hs = HoloScript()
+
+# Parse HoloScript code
+ast = hs.parse("""
+composition "My Scene" {
+  object "Crystal" @grabbable @glowing {
+    geometry: "sphere"
+    color: "#00ffff"
+  }
+}
+""")
+
+# Validate code
+result = hs.validate(ast)
+if result.valid:
+    print("✅ Valid HoloScript!")
+else:
+    for error in result.errors:
+        print(f"❌ Line {error.line}: {error.message}")
+
+# Generate from natural language
+scene = hs.generate("a floating island with glowing crystals")
+print(scene.code)
+
+# Create shareable link
+share = hs.share(scene.code, title="My VR Scene", platform="x")
+print(f"Playground: {share.playground_url}")
+print(f"Tweet: {share.tweet_text}")
+```
+
+## Features
+
+- **Parsing**: Parse `.hs`, `.hsplus`, and `.holo` files
+- **Validation**: Validate syntax with AI-friendly error messages
+- **Generation**: Generate HoloScript from natural language
+- **Rendering**: Generate preview images/GIFs
+- **Sharing**: Create X-optimized shareable links
+
+## For AI Agents (Grok, etc.)
+
+```python
+# Grok integration example
+from holoscript import HoloScript
+
+hs = HoloScript(api_key="your-api-key")  # Optional for remote rendering
+
+# Generate scene from user prompt
+user_prompt = "Create a VR scene with a floating castle"
+scene = hs.generate(user_prompt)
+
+# Validate
+if hs.validate(scene.code).valid:
+    # Create shareable preview
+    preview = hs.render(scene.code, format="gif", duration=3000)
+    share = hs.share(scene.code, title="Floating Castle", platform="x")
+    
+    # Return to user
+    print(f"Here's your VR scene: {share.playground_url}")
+    print(f"Preview: {preview.url}")
+```
+
+## API Reference
+
+See [full documentation](https://holoscript.dev/python) for complete API reference.

holoscript-1.0.0/README.md

@@ -0,0 +1,80 @@
+# HoloScript Python Bindings
+
+Python bindings for HoloScript - parse, validate, and generate HoloScript code from Python.
+
+## Installation
+
+```bash
+pip install holoscript
+```
+
+## Quick Start
+
+```python
+from holoscript import HoloScript, parse, validate, generate
+
+# Initialize
+hs = HoloScript()
+
+# Parse HoloScript code
+ast = hs.parse("""
+composition "My Scene" {
+  object "Crystal" @grabbable @glowing {
+    geometry: "sphere"
+    color: "#00ffff"
+  }
+}
+""")
+
+# Validate code
+result = hs.validate(ast)
+if result.valid:
+    print("✅ Valid HoloScript!")
+else:
+    for error in result.errors:
+        print(f"❌ Line {error.line}: {error.message}")
+
+# Generate from natural language
+scene = hs.generate("a floating island with glowing crystals")
+print(scene.code)
+
+# Create shareable link
+share = hs.share(scene.code, title="My VR Scene", platform="x")
+print(f"Playground: {share.playground_url}")
+print(f"Tweet: {share.tweet_text}")
+```
+
+## Features
+
+- **Parsing**: Parse `.hs`, `.hsplus`, and `.holo` files
+- **Validation**: Validate syntax with AI-friendly error messages
+- **Generation**: Generate HoloScript from natural language
+- **Rendering**: Generate preview images/GIFs
+- **Sharing**: Create X-optimized shareable links
+
+## For AI Agents (Grok, etc.)
+
+```python
+# Grok integration example
+from holoscript import HoloScript
+
+hs = HoloScript(api_key="your-api-key")  # Optional for remote rendering
+
+# Generate scene from user prompt
+user_prompt = "Create a VR scene with a floating castle"
+scene = hs.generate(user_prompt)
+
+# Validate
+if hs.validate(scene.code).valid:
+    # Create shareable preview
+    preview = hs.render(scene.code, format="gif", duration=3000)
+    share = hs.share(scene.code, title="Floating Castle", platform="x")
+    
+    # Return to user
+    print(f"Here's your VR scene: {share.playground_url}")
+    print(f"Preview: {preview.url}")
+```
+
+## API Reference
+
+See [full documentation](https://holoscript.dev/python) for complete API reference.

holoscript-1.0.0/holoscript/__init__.py

@@ -0,0 +1,48 @@
+"""
+HoloScript Python Bindings
+
+Parse, validate, generate, and render HoloScript code from Python.
+Perfect for AI agents like Grok to build VR experiences.
+"""
+
+from holoscript.client import HoloScript
+from holoscript.parser import parse, parse_holo, parse_hsplus
+from holoscript.validator import validate, ValidationResult, ValidationError
+from holoscript.generator import generate, generate_object, generate_scene
+from holoscript.renderer import render, RenderResult
+from holoscript.sharer import share, ShareResult
+from holoscript.traits import list_traits, explain_trait, suggest_traits
+
+__version__ = "1.0.0"
+__all__ = [
+    # Main client
+    "HoloScript",
+    
+    # Parsing
+    "parse",
+    "parse_holo",
+    "parse_hsplus",
+    
+    # Validation
+    "validate",
+    "ValidationResult",
+    "ValidationError",
+    
+    # Generation
+    "generate",
+    "generate_object",
+    "generate_scene",
+    
+    # Rendering
+    "render",
+    "RenderResult",
+    
+    # Sharing
+    "share",
+    "ShareResult",
+    
+    # Traits
+    "list_traits",
+    "explain_trait",
+    "suggest_traits",
+]

holoscript-1.0.0/holoscript/client.py

@@ -0,0 +1,266 @@
+"""
+HoloScript Client - Main interface for HoloScript operations.
+"""
+
+from typing import Optional, Dict, Any, List
+import requests
+
+from holoscript.parser import parse, parse_holo, parse_hsplus, ParseResult
+from holoscript.validator import validate, ValidationResult
+from holoscript.generator import generate_object, generate_scene, GenerateResult
+from holoscript.renderer import render, RenderResult
+from holoscript.sharer import share, ShareResult
+from holoscript.traits import list_traits, explain_trait, suggest_traits
+
+
+class HoloScript:
+    """
+    Main HoloScript client for AI agents and Python applications.
+    
+    Example:
+        >>> hs = HoloScript()
+        >>> scene = hs.generate("a glowing crystal in a dark cave")
+        >>> if hs.validate(scene.code).valid:
+        ...     share = hs.share(scene.code, platform="x")
+        ...     print(share.playground_url)
+    """
+    
+    DEFAULT_API_URL = "https://api.holoscript.dev"
+    
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        local_mode: bool = False
+    ):
+        """
+        Initialize HoloScript client.
+        
+        Args:
+            api_key: Optional API key for remote rendering/services
+            api_url: Custom API URL (defaults to https://api.holoscript.dev)
+            local_mode: If True, use local parsing only (no remote calls)
+        """
+        self.api_key = api_key
+        self.api_url = api_url or self.DEFAULT_API_URL
+        self.local_mode = local_mode
+        
+        self._session = requests.Session()
+        if api_key:
+            self._session.headers["Authorization"] = f"Bearer {api_key}"
+    
+    # === Parsing ===
+    
+    def parse(self, code: str, format: str = "auto") -> ParseResult:
+        """
+        Parse HoloScript code into an AST.
+        
+        Args:
+            code: HoloScript source code
+            format: Format hint - "hs", "hsplus", "holo", or "auto"
+        
+        Returns:
+            ParseResult with AST and any errors
+        """
+        if format == "holo" or (format == "auto" and "composition" in code):
+            return parse_holo(code)
+        else:
+            return parse_hsplus(code)
+    
+    # === Validation ===
+    
+    def validate(
+        self,
+        code: str,
+        include_warnings: bool = True,
+        include_suggestions: bool = True
+    ) -> ValidationResult:
+        """
+        Validate HoloScript code for errors.
+        
+        Args:
+            code: HoloScript source code or ParseResult
+            include_warnings: Include warnings in result
+            include_suggestions: Include fix suggestions
+        
+        Returns:
+            ValidationResult with errors, warnings, and suggestions
+        """
+        return validate(
+            code,
+            include_warnings=include_warnings,
+            include_suggestions=include_suggestions
+        )
+    
+    # === Generation ===
+    
+    def generate(
+        self,
+        description: str,
+        format: str = "holo",
+        style: str = "detailed"
+    ) -> GenerateResult:
+        """
+        Generate HoloScript code from natural language.
+        
+        Args:
+            description: Natural language description of the scene
+            format: Output format - "hs", "hsplus", or "holo"
+            style: Style - "minimal", "detailed", or "production"
+        
+        Returns:
+            GenerateResult with code and metadata
+        """
+        return generate_scene(description, format=format, style=style)
+    
+    def generate_object(
+        self,
+        description: str,
+        format: str = "hsplus"
+    ) -> GenerateResult:
+        """
+        Generate a single object from description.
+        
+        Args:
+            description: Natural language description of the object
+            format: Output format
+        
+        Returns:
+            GenerateResult with object code
+        """
+        return generate_object(description, format=format)
+    
+    # === Rendering ===
+    
+    def render(
+        self,
+        code: str,
+        format: str = "png",
+        resolution: tuple = (800, 600),
+        camera_position: tuple = (0, 2, 5),
+        duration: int = 3000,
+        quality: str = "preview"
+    ) -> RenderResult:
+        """
+        Render HoloScript code to an image or video.
+        
+        Args:
+            code: HoloScript source code
+            format: Output format - "png", "gif", "mp4", "webp"
+            resolution: (width, height) tuple
+            camera_position: (x, y, z) camera position
+            duration: Animation duration in ms (for gif/mp4)
+            quality: "draft", "preview", or "production"
+        
+        Returns:
+            RenderResult with URL or base64 data
+        """
+        return render(
+            code,
+            format=format,
+            resolution=resolution,
+            camera_position=camera_position,
+            duration=duration,
+            quality=quality,
+            api_url=self.api_url if not self.local_mode else None,
+            api_key=self.api_key
+        )
+    
+    # === Sharing ===
+    
+    def share(
+        self,
+        code: str,
+        title: str = "HoloScript Scene",
+        description: str = "Interactive 3D scene built with HoloScript",
+        platform: str = "x"
+    ) -> ShareResult:
+        """
+        Create shareable links for the code.
+        
+        Args:
+            code: HoloScript source code
+            title: Scene title
+            description: Scene description
+            platform: Target platform - "x", "generic", "codesandbox", "stackblitz"
+        
+        Returns:
+            ShareResult with URLs and embed codes
+        """
+        return share(
+            code,
+            title=title,
+            description=description,
+            platform=platform
+        )
+    
+    # === Traits ===
+    
+    def list_traits(self, category: Optional[str] = None) -> Dict[str, List[str]]:
+        """
+        List available VR traits.
+        
+        Args:
+            category: Filter by category (interaction, physics, visual, etc.)
+        
+        Returns:
+            Dictionary of traits by category
+        """
+        return list_traits(category)
+    
+    def explain_trait(self, trait: str) -> Dict[str, Any]:
+        """
+        Get detailed documentation for a trait.
+        
+        Args:
+            trait: Trait name (with or without @)
+        
+        Returns:
+            Trait documentation dictionary
+        """
+        return explain_trait(trait)
+    
+    def suggest_traits(
+        self,
+        description: str,
+        context: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Suggest appropriate traits for an object.
+        
+        Args:
+            description: Object description
+            context: Additional context
+        
+        Returns:
+            Suggested traits with reasoning
+        """
+        return suggest_traits(description, context)
+    
+    # === Utility ===
+    
+    def quick_test(self, code: str) -> Dict[str, Any]:
+        """
+        Quick test: parse, validate, and return summary.
+        
+        Args:
+            code: HoloScript source code
+        
+        Returns:
+            Dictionary with parse result, validation, and stats
+        """
+        parse_result = self.parse(code)
+        validation = self.validate(code)
+        
+        return {
+            "parsed": parse_result.success,
+            "valid": validation.valid,
+            "errors": validation.errors,
+            "warnings": validation.warnings,
+            "stats": {
+                "lines": len(code.split("\n")),
+                "characters": len(code),
+                "objects": len(parse_result.objects) if hasattr(parse_result, "objects") else 0,
+                "traits": len(parse_result.traits) if hasattr(parse_result, "traits") else 0,
+            }
+        }