@aci-metrics/score 0.0.1

package/README.md

@@ -0,0 +1,228 @@
+# ACI Local Scorer (Tier 1)
+
+Air-gapped local scoring executable for ACI (AI Collaboration Index) analysis.
+
+## Requirements
+
+- macOS with Apple Silicon (M1/M2/M3) recommended
+- 16GB+ RAM
+- Node.js 18+
+- Xcode Command Line Tools (for native compilation)
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+This installs:
+- `node-llama-cpp` - Native bindings for llama.cpp (compiles on install)
+- `simple-statistics` - Statistical analysis for norming and z-scores
+
+### 2. Download a Model
+
+The local scorer supports multiple models. Download the one you want to use.
+
+**Default: Qwen 2.5 1.5B (~900MB)**
+```bash
+huggingface-cli download bartowski/Qwen2.5-1.5B-Instruct-GGUF \
+  Qwen2.5-1.5B-Instruct-Q4_K_M.gguf \
+  --local-dir ./models
+```
+
+**Alternative: Llama 3.2 3B (~1.8GB)**
+```bash
+huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF \
+  Llama-3.2-3B-Instruct-Q4_K_M.gguf \
+  --local-dir ./models
+```
+
+**Alternative: Phi 3.5 Mini (~2.2GB)**
+```bash
+huggingface-cli download bartowski/Phi-3.5-mini-instruct-GGUF \
+  Phi-3.5-mini-instruct-Q4_K_M.gguf \
+  --local-dir ./models
+```
+
+**Alternative: Gemma 2 2B (~1.4GB)**
+```bash
+huggingface-cli download bartowski/gemma-2-2b-it-GGUF \
+  gemma-2-2b-it-Q4_K_M.gguf \
+  --local-dir ./models
+```
+
+### 3. Verify Installation
+
+```bash
+npm test
+```
+
+This runs the model test which verifies everything is configured correctly.
+
+## Configuration
+
+All configuration is in the `config/` directory.
+
+### Switching Models
+
+Edit `config/default.json` and change the model id:
+
+```json
+{
+  "model": {
+    "id": "llama-3.2-3b"
+  }
+}
+```
+
+Available models:
+- `qwen2.5-1.5b` (default)
+- `phi-3.5-mini`
+- `llama-3.2-3b`
+- `gemma-2-2b`
+
+### Switching Inference Runtime
+
+The scorer supports two inference backends:
+
+**node-llama-cpp (default)** - Loads GGUF files directly
+```json
+{
+  "runtime": {
+    "provider": "node-llama-cpp"
+  }
+}
+```
+
+**Ollama** - Uses Ollama HTTP API
+```json
+{
+  "runtime": {
+    "provider": "ollama"
+  }
+}
+```
+
+For Ollama, make sure the server is running and the model is pulled:
+```bash
+ollama pull qwen2.5:1.5b
+ollama serve
+```
+
+### Command Line Overrides
+
+You can override config settings from the command line:
+
+```bash
+# Test with a different model
+node test-model.js --model=llama-3.2-3b
+
+# Test with Ollama backend
+node test-model.js --provider=ollama
+
+# Combine both
+node test-model.js --model=gemma-2-2b --provider=ollama
+```
+
+## Directory Structure
+
+```
+local-scorer/
+  config/
+    default.json        # Runtime configuration
+    models.json         # Model registry
+  lib/
+    provider-factory.js # Creates the right provider
+    providers/
+      base.js           # Abstract provider interface
+      node-llama-cpp.js # GGUF file loader
+      ollama.js         # Ollama HTTP client
+  models/
+    *.gguf              # Downloaded model files
+  prompts/
+    qwen.txt            # Qwen prompt template
+    llama.txt           # Llama prompt template
+    phi.txt             # Phi prompt template
+    gemma.txt           # Gemma prompt template
+  test-model.js         # Model verification script
+  package.json
+  README.md
+```
+
+## Available Models
+
+| Model | Size | Best For |
+|-------|------|----------|
+| qwen2.5-1.5b | ~900MB | Fast, reliable JSON output |
+| phi-3.5-mini | ~2.2GB | Strong reasoning |
+| llama-3.2-3b | ~1.8GB | General capabilities |
+| gemma-2-2b | ~1.4GB | Fast inference |
+
+## Programmatic Usage
+
+```javascript
+var createProvider = require('./lib/provider-factory');
+
+async function main() {
+    // Create provider (reads from config/default.json)
+    var provider = createProvider();
+
+    // Or override settings
+    var provider = createProvider({
+        modelId: 'llama-3.2-3b',
+        provider: 'node-llama-cpp'
+    });
+
+    // Initialize (loads model)
+    await provider.initialize();
+
+    // Generate with schema enforcement
+    var schema = {
+        type: 'object',
+        properties: {
+            task_type: { type: 'string', enum: ['feature', 'bugfix'] },
+            complexity: { type: 'number', minimum: 1, maximum: 10 }
+        },
+        required: ['task_type', 'complexity']
+    };
+
+    var result = await provider.generate('Classify this task...', schema);
+    console.log(result);
+
+    // Clean up
+    await provider.destroy();
+}
+
+main();
+```
+
+## Troubleshooting
+
+### node-llama-cpp fails to compile
+
+Make sure you have Xcode Command Line Tools installed:
+```bash
+xcode-select --install
+```
+
+### Out of memory errors
+
+The models require 2-4GB of RAM when loaded. Close other applications if running low.
+
+### Model file not found
+
+Ensure the model file is in the `./models/` directory with the exact filename from `config/models.json`.
+
+### Ollama connection refused
+
+Make sure Ollama is running:
+```bash
+ollama serve
+```
+
+And the model is pulled:
+```bash
+ollama pull qwen2.5:1.5b
+```