@ebowwa/logic-spec 1.0.0

package/examples/minimal.yaml

@@ -0,0 +1,49 @@
+# logic.yaml - Minimal Example
+# Simple data transformation
+
+meta:
+  spec_version: "1.0"
+  name: string-reverser
+  version: "1.0.0"
+  description: Reverses input strings
+
+inputs:
+  - name: text
+    type: string
+    required: true
+    description: The string to reverse
+
+outputs:
+  - name: reversed
+    type: string
+    description: The reversed string
+
+logic:
+  - id: reverse
+    type: transform
+    input: text
+    output: reversed
+    algorithm: |
+      1. Take input string
+      2. Reverse character order
+      3. Return reversed string
+    complexity: O(n)
+
+tests:
+  - name: basic_reverse
+    given:
+      text: "hello"
+    expect:
+      reversed: "olleh"
+
+  - name: empty_string
+    given:
+      text: ""
+    expect:
+      reversed: ""
+
+  - name: single_char
+    given:
+      text: "a"
+    expect:
+      reversed: "a"

package/examples/smart-glass-supervisor.yaml

@@ -0,0 +1,330 @@
+# logic.yaml - Smart Glass Supervisor
+# Real-time visual analysis for smart glasses
+
+meta:
+  spec_version: "1.0"
+  name: smart-glass-supervisor
+  version: "1.0.0"
+  description: Real-time visual segmentation and AI analysis
+  language_target: any
+
+inputs:
+  - name: camera_stream
+    type: MediaStream
+    required: true
+    schema:
+      frames_per_second: 30
+      resolution: [1280, 720]
+      format: video/webm
+
+  - name: user_query
+    type: string
+    required: false
+    default: null
+    description: Optional voice/text query from user
+
+  - name: settings
+    type: Settings
+    required: false
+    default:
+      overlay_enabled: true
+      segmentation_enabled: true
+      language: en
+
+outputs:
+  - name: analysis_result
+    type: AnalysisResult
+    description: Real-time analysis output
+
+  - name: composite_stream
+    type: MediaStream
+    description: Video stream with overlay
+
+types:
+  MediaStream:
+    fields:
+      frames_per_second: number
+      resolution: array
+      format: string
+
+  Settings:
+    fields:
+      overlay_enabled: boolean
+      segmentation_enabled: boolean
+      language: string
+
+  Frame:
+    fields:
+      data: string
+      timestamp: number
+      width: number
+      height: number
+
+  Segment:
+    fields:
+      label: string
+      bbox: BoundingBox
+      confidence: number
+      color: string
+
+  BoundingBox:
+    fields:
+      x: number
+      y: number
+      width: number
+      height: number
+
+  AnalysisResult:
+    fields:
+      text_response: string
+      segments: array
+      timestamp: number
+      confidence: number
+      processing_time_ms: number
+
+  InferenceError:
+    enum: [TIMEOUT, RATE_LIMITED, MODEL_ERROR, INVALID_INPUT]
+
+logic:
+  - id: capture_frame
+    type: transform
+    input: camera_stream
+    output: frame
+    algorithm: |
+      1. Extract current frame from video stream
+      2. Encode as base64/jpeg
+      3. Attach timestamp
+      4. Return Frame object
+    complexity: O(1)
+
+  - id: build_prompt
+    type: transform
+    input: [frame, user_query, settings]
+    output: prompt
+    algorithm: |
+      1. Base prompt: "Analyze this image for a smart glasses user"
+      2. If user_query exists, append: "User asks: {query}"
+      3. If segmentation_enabled, append segmentation instructions
+      4. Return complete prompt string
+
+  - id: gemini_inference
+    type: inference
+    input: [frame, prompt]
+    output: raw_response
+    algorithm: |
+      1. Send frame + prompt to Gemini 2.0 Flash
+      2. Request structured response with segments
+      3. Parse JSON response
+      4. Return {text, segments, confidence}
+
+  - id: parse_segments
+    type: transform
+    input: raw_response
+    output: segments
+    algorithm: |
+      1. Extract segment array from response
+      2. Validate each segment has required fields
+      3. Normalize bounding box coordinates to frame dimensions
+      4. Assign colors based on segment labels
+      5. Return Segment[]
+
+  - id: render_overlay
+    type: transform
+    input: [frame, segments, settings]
+    output: overlay_canvas
+    algorithm: |
+      1. Create transparent canvas matching frame dimensions
+      2. For each segment:
+         a. Draw bounding box with segment color
+         b. Draw label text above box
+         c. Draw confidence percentage
+      3. Return canvas with overlay
+
+  - id: composite_streams
+    type: transform
+    input: [camera_stream, overlay_canvas]
+    output: composite_stream
+    algorithm: |
+      1. Layer overlay canvas on video stream
+      2. Maintain original frame rate
+      3. Apply alpha blending for overlay transparency
+      4. Return composite MediaStream
+
+  - id: format_result
+    type: aggregate
+    input: [raw_response, segments, processing_time]
+    output: analysis_result
+    algorithm: |
+      1. Combine text response from inference
+      2. Include parsed segments
+      3. Calculate overall confidence (average of segment confidences)
+      4. Attach processing time metric
+      5. Return AnalysisResult
+
+state:
+  initial: idle
+  persist: false
+  states:
+    idle:
+      description: Camera not active
+    capturing:
+      description: Actively capturing frames
+    processing:
+      description: Frame sent to AI, awaiting response
+    displaying:
+      description: Showing analysis results
+
+  transitions:
+    - from: idle
+      to: capturing
+      trigger: camera_enabled
+      action: capture_frame
+
+    - from: capturing
+      to: processing
+      trigger: frame_ready
+      action: gemini_inference
+
+    - from: processing
+      to: displaying
+      trigger: inference_complete
+      action: [parse_segments, render_overlay, composite_streams]
+
+    - from: displaying
+      to: capturing
+      trigger: display_complete
+
+    - from: capturing
+      to: idle
+      trigger: camera_disabled
+
+    - from: processing
+      to: capturing
+      trigger: inference_error
+
+flows:
+  - name: realtime_analysis
+    description: Full real-time analysis pipeline
+    steps:
+      - capture_frame
+      - build_prompt
+      - gemini_inference
+      - parse_segments
+      - render_overlay
+      - composite_streams
+      - format_result
+    parallel: false
+    timeout_ms: 500
+
+  - name: frame_only
+    description: Capture without AI analysis
+    steps:
+      - capture_frame
+    timeout_ms: 33
+
+failures:
+  - code: E001
+    condition: "camera_stream.unavailable"
+    severity: critical
+    recovery:
+      strategy: escalate
+    message: Camera stream not available
+
+  - code: E002
+    condition: "gemini_inference.timeout > 30000ms"
+    severity: error
+    recovery:
+      strategy: retry
+      retry_count: 2
+    message: AI inference timed out
+
+  - code: E003
+    condition: "gemini_inference.rate_limited"
+    severity: warning
+    recovery:
+      strategy: fallback
+      fallback_to: cached_response
+    message: API rate limit exceeded
+
+  - code: E004
+    condition: "memory_usage > 256MB"
+    severity: warning
+    recovery:
+      strategy: ignore
+    message: High memory usage detected
+
+constraints:
+  latency_max_ms: 500
+  frame_drop_tolerance: 0.05
+  memory_limit_mb: 256
+  throughput_min_rps: 30
+
+dependencies:
+  - name: gemini_api
+    type: external_service
+    contract: VisionAPI
+    required: true
+    timeout_ms: 30000
+    auth: api_key
+
+  - name: camera_hardware
+    type: hardware
+    contract: CameraDevice
+    required: true
+
+observability:
+  metrics:
+    - name: frame_capture_rate
+      type: gauge
+      unit: fps
+    - name: inference_latency_ms
+      type: histogram
+      unit: ms
+      labels: [model, success]
+    - name: segment_count
+      type: gauge
+    - name: frame_drops_total
+      type: counter
+
+  logs:
+    level: info
+    include: [frame_timestamp, query, segment_count, latency_ms]
+    exclude: [frame_data, raw_response]
+
+  traces:
+    enabled: true
+    sample_rate: 0.1
+
+tests:
+  - name: happy_path_with_query
+    given:
+      camera_stream: valid_stream
+      user_query: "What objects are in front of me?"
+      settings: {overlay_enabled: true, segmentation_enabled: true}
+    expect:
+      analysis_result.text_response: "!null"
+      analysis_result.segments: "type:array"
+      analysis_result.confidence: ">= 0.5"
+
+  - name: happy_path_no_query
+    given:
+      camera_stream: valid_stream
+      user_query: null
+    expect:
+      analysis_result.text_response: "!null"
+      analysis_result.segments: "type:array"
+
+  - name: segmentation_disabled
+    given:
+      camera_stream: valid_stream
+      settings: {overlay_enabled: true, segmentation_enabled: false}
+    expect:
+      analysis_result.segments: []
+
+  - name: inference_timeout
+    given:
+      camera_stream: slow_stream
+    when: realtime_analysis
+    expect:
+      analysis_result: "!null"
+    timeout_ms: 60000

package/examples/state-machine.yaml

@@ -0,0 +1,106 @@
+# logic.yaml - State Machine Example
+# Traffic light controller
+
+meta:
+  spec_version: "1.0"
+  name: traffic-light
+  version: "1.0.0"
+  description: Traffic light state machine with timing
+
+inputs:
+  - name: event
+    type: Event
+    required: true
+    schema:
+      type: timer_expired | emergency_override | reset
+
+outputs:
+  - name: light_state
+    type: LightState
+    schema:
+      current: string
+      duration_ms: number
+
+types:
+  Event:
+    enum: [timer_expired, emergency_override, reset]
+
+  LightState:
+    fields:
+      current: string
+      duration_ms: number
+
+logic:
+  - id: determine_next_state
+    type: decision
+    input: [current_state, event]
+    output: next_state
+    algorithm: |
+      1. If event is emergency_override, return "red"
+      2. If event is reset, return "green"
+      3. Otherwise, follow normal cycle:
+         - green -> yellow
+         - yellow -> red
+         - red -> green
+
+  - id: calculate_duration
+    type: compute
+    input: next_state
+    output: duration_ms
+    algorithm: |
+      1. green: 30000ms (30 seconds)
+      2. yellow: 5000ms (5 seconds)
+      3. red: 25000ms (25 seconds)
+
+state:
+  initial: red
+  persist: true
+  states:
+    green:
+      description: Vehicles may proceed
+    yellow:
+      description: Vehicles should prepare to stop
+    red:
+      description: Vehicles must stop
+
+  transitions:
+    - from: red
+      to: green
+      trigger: timer_expired
+      action: determine_next_state
+
+    - from: green
+      to: yellow
+      trigger: timer_expired
+
+    - from: yellow
+      to: red
+      trigger: timer_expired
+
+    - from: green
+      to: red
+      trigger: emergency_override
+
+    - from: yellow
+      to: red
+      trigger: emergency_override
+
+constraints:
+  latency_max_ms: 100
+  availability_percent: 99.99
+
+tests:
+  - name: normal_cycle
+    given:
+      current_state: red
+      event: timer_expired
+    expect:
+      light_state.current: green
+      light_state.duration_ms: 30000
+
+  - name: emergency
+    given:
+      current_state: green
+      event: emergency_override
+    expect:
+      light_state.current: red

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ebowwa/logic-spec",
+  "version": "1.0.0",
+  "description": "Language-agnostic standard for extracting pure logic from implementations into logic.yaml",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "logic-validate": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema.json",
+    "SPEC.md",
+    "REFERENCE.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts ./src/cli.ts --outdir ./dist",
+    "validate": "bun run src/cli.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "logic",
+    "specification",
+    "yaml",
+    "ai",
+    "agents",
+    "code-generation",
+    "documentation",
+    "schema"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces",
+    "directory": "cerebralvalley/032126/smart-glass-supervisor/docs/logic-spec"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}