Llm integration, production readiness - phase 1: week 1 of 4 complete

.env.example

@@ -0,0 +1,80 @@
+# ===================================================================
+# MODERN APPROACH: Use AI Model Profiles (Recommended)
+# ===================================================================
+# Specification: docs/specs/13-llm-profile-management.md
+#
+# Create and manage connection profiles for different LLM providers:
+#
+#   machine-dream llm profile add \
+#     --name lm-studio-local \
+#     --provider lmstudio \
+#     --base-url http://localhost:1234/v1 \
+#     --model qwen3-30b \
+#     --set-default
+#
+#   machine-dream llm profile add \
+#     --name openai-gpt4 \
+#     --provider openai \
+#     --base-url https://api.openai.com/v1 \
+#     --api-key "${OPENAI_API_KEY}" \
+#     --model gpt-4
+#
+# View all profiles:
+#   machine-dream llm profile list
+#
+# Switch active profile:
+#   machine-dream llm profile set <name>
+#
+# Test connection:
+#   machine-dream llm profile test
+#
+# Use specific profile:
+#   machine-dream llm play puzzles/easy-01.json --profile openai-gpt4
+#
+# Profiles are stored at: ~/.machine-dream/llm-profiles.json
+
+# ===================================================================
+# API Keys (Referenced by Profiles)
+# ===================================================================
+# Store sensitive API keys here, reference in profiles as ${VAR_NAME}
+# Profiles will automatically resolve these environment variables
+
+# OpenAI API Key (for openai provider profiles)
+# OPENAI_API_KEY=your-openai-key-here
+
+# Anthropic API Key (for anthropic provider profiles)
+# ANTHROPIC_API_KEY=your-anthropic-key-here
+
+# OpenRouter API Key (for openrouter provider profiles)
+# OPENROUTER_API_KEY=your-openrouter-key-here
+
+# Custom API Keys (for custom provider profiles)
+# CUSTOM_LLM_API_KEY=your-custom-key-here
+
+# ===================================================================
+# LEGACY: Direct Environment Variables (DEPRECATED)
+# ===================================================================
+# These environment variables are deprecated in favor of profiles.
+# They remain for backward compatibility but will be removed in v1.0.
+#
+# Migration: Run `machine-dream llm profile add` to create a profile
+# instead of using these variables.
+#
+# Legacy LM Studio Connection
+# LLM_BASE_URL=http://localhost:1234/v1
+# LLM_MODEL=qwen3-30b
+#
+# Legacy Generation Parameters
+# LLM_TEMPERATURE=0.7
+# LLM_MAX_TOKENS=1024
+# LLM_TIMEOUT=60000
+#
+# Legacy Learning Settings
+# LLM_MEMORY_ENABLED=true
+# LLM_MAX_HISTORY_MOVES=20
+
+# ===================================================================
+# AgentDB Configuration
+# ===================================================================
+# AgentDB database path for memory persistence
+AGENTDB_PATH=./agent.db

.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": "warn"
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main, llm_integration]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run typecheck
+        run: npm run typecheck
+
+      - name: Run lint
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test -- --run
+
+      - name: Build project
+        run: npm run build
+
+      # Optional: Upload coverage (can be enabled later with Codecov)
+      # - name: Test coverage
+      #   run: npm test -- --coverage --run
+      #
+      # - name: Upload coverage to Codecov
+      #   uses: codecov/codecov-action@v3
+      #   with:
+      #     files: ./coverage/coverage-final.json

.machine-dream.json

@@ -0,0 +1,58 @@
+{
+  "memorySystem": "agentdb",
+  "enableRL": true,
+  "enableReflexion": true,
+  "enableSkillLibrary": true,
+  "solving": {
+    "maxIterations": 50,
+    "maxSolveTime": 300000,
+    "reflectionInterval": 5,
+    "attentionWindowSize": 10,
+    "backtrackEnabled": false,
+    "guessThreshold": 0.3,
+    "strategies": [
+      "naked-single",
+      "hidden-single",
+      "pointing-pairs",
+      "box-line-reduction",
+      "naked-pairs",
+      "x-wing"
+    ]
+  },
+  "dreaming": {
+    "schedule": "after-session",
+    "compressionRatio": 10,
+    "abstractionLevels": 4,
+    "minSuccessRate": 0.7
+  },
+  "agentdb": {
+    "dbPath": ".agentdb",
+    "preset": "medium",
+    "quantization": "scalar",
+    "indexing": "hnsw"
+  },
+  "benchmarking": {
+    "enabled": true,
+    "outputDir": "./benchmarks",
+    "parallel": 1
+  },
+  "logging": {
+    "level": "info",
+    "outputDir": "./logs",
+    "format": "json"
+  },
+  "demo": {
+    "mode": false,
+    "speed": "realtime",
+    "pauseOnInsight": false
+  },
+  "hooks": {
+    "preTask": null,
+    "postTask": null,
+    "preEdit": null,
+    "postEdit": null,
+    "sessionEnd": null,
+    "sessionRestore": null
+  },
+  "key": "value"
+}

CLAUDE.md

@@ -350,3 +350,51 @@ NEVER create files unless they're absolutely necessary for achieving your goal.
 ALWAYS prefer editing an existing file to creating a new one.
 NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
 Never save working files, text/mds and tests to the root folder.
+
+## 📋 Spec-Based Development (MANDATORY)
+
+**CRITICAL RULE**: Always build to spec. No implementation changes unless outlined in specification documents.
+
+### Specification-First Workflow
+
+1. **Before implementing ANY feature**:
+   - Check if feature is defined in `/docs/specs/`
+   - If NOT defined → Update the spec first, then implement
+   - If defined → Implement exactly as specified
+
+2. **Specification Documents** (in order of dependency):
+   | Spec | Document | Purpose |
+   |------|----------|---------|
+   | 01 | [Puzzle Engine](docs/specs/01-puzzle-engine-spec.md) | Sudoku generation, validation, rules |
+   | 02 | [Memory System](docs/specs/02-memory-system-spec.md) | AgentDB integration & persistence |
+   | 03 | [GRASP Loop](docs/specs/03-grasp-loop-spec.md) | Generate, Review, Absorb, Synthesize, Persist |
+   | 04 | [Attention Mechanism](docs/specs/04-attention-mechanism-spec.md) | Focus and priority system |
+   | 05 | [Dreaming Pipeline](docs/specs/05-dreaming-pipeline-spec.md) | 5-phase consolidation |
+   | 06 | [Benchmarking Framework](docs/specs/06-benchmarking-framework-spec.md) | Performance testing |
+   | 07 | [Integration Orchestration](docs/specs/07-integration-orchestration-spec.md) | System orchestration |
+   | 08 | [AgentDB Integration](docs/specs/08-agentdb-integration-spec.md) | Native AgentDB features |
+   | 09 | [CLI Interface](docs/specs/09-cli-interface-spec.md) | Command-line interface |
+   | 10 | [Terminal UI](docs/specs/10-terminal-menu-interface-spec.md) | Interactive TUI with Ink |
+   | 11 | [LLM Integration](docs/specs/11-llm-sudoku-player.md) | AI model Sudoku player |
+   | 12 | [Puzzle Generation](docs/specs/12-randomized-puzzle-generation.md) | Seeded random puzzles |
+   | 13 | [Profile Management](docs/specs/13-llm-profile-management.md) | AI model connection profiles |
+   | 14 | [Console Menu](docs/specs/14-console-menu-interface-spec.md) | TUI console & help system |
+
+3. **When specs conflict with implementation ideas**:
+   - Specs are authoritative
+   - Propose spec updates if needed
+   - Never implement unspecified behavior
+
+4. **Verification Checklist** (before any PR):
+   - [ ] All new types defined in specs
+   - [ ] All event types registered in Spec 07
+   - [ ] All CLI commands match Spec 09
+   - [ ] All TUI screens match Spec 10
+   - [ ] Tests verify spec compliance
+
+### Why Spec-Based Development?
+
+- **Consistency**: All components follow the same contracts
+- **Traceability**: Every feature maps to a specification
+- **Reviewability**: Changes are validated against specs
+- **Maintainability**: Specs serve as living documentation