npm package: @josfox/jos
Description: Stoic kernel for AI agent orchestration. Zero dependencies. Offline first.
Author: JOS Open Standards Foundation
Latest version: 4.1.0

# JOS Open Standard

> **The minimal atomic unit for fractal, intention-native Adaptive Intelligent Agents.**

JOS (JSON Object Specification) introduces a novel fractal paradigm for AI orchestration—**intention-based, efficient, portable, secure, and adaptive by design.** Every `.jos` artifact encodes both the *why* (intention) and the *how* (execution) as a single, versioned, cryptographically verifiable unit.

[![npm](https://img.shields.io/npm/v/@josfox/jos?label=%40josfox%2Fjos)](https://www.npmjs.com/package/@josfox/jos)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Specification](https://img.shields.io/badge/Spec-v0.0.7-purple.svg)](https://github.com/josfox-ai/jos-format-spec)

---

## ✨ What's New in v4.1.0

### 🧠 LLM Integration & Prompt Enhancement
- **Native LLM Support**: `jos llm <artifact>` crystallizes `.jos` intentions into chat-oriented prompts for any AI/LLM/GPT
- **Multi-Adapter Architecture**: Ollama (local), Gemini, OpenAI, Anthropic adapters built-in
- **Prompt Enhancement**: Automatically enriches prompts with guardrails, context, and success criteria

### 🦊 Introducing ALAIA
**Adaptive Learning AI Agent** — the nano-agent framework that bonds to `.jos` artifacts, enabling:
- Offline-first execution with Ollama
- Real-time guardrail enforcement
- Adaptive learning from execution feedback

### 🚀 Quick Start with Ollama
Run locally with zero cloud dependencies:
```bash
# Install JOS
npm install -g @josfox/jos

# Clone starter examples
git clone https://github.com/josfox-ai/jos-repo-starter
cd jos-repo-starter

# Run with local Ollama
jos llm examples/hello-ai.jos --adapter ollama
```

---

## 🎯 The Fractal Paradigm

> *"Everything is a prompt. Every prompt is an intention. Every intention is an artifact."*

JOS artifacts are **self-similar at all scales**—from atomic single-step automations to orchestrated enterprise workflows. The same schema, the same validation, the same security model.

```
┌─────────────────────────────────────────────────────────────────┐
│                      .jos ARTIFACT                               │
├─────────────────────────────────────────────────────────────────┤
│   MAGIC Kernel (Why + What)    │   JOSFOXAI Kernel (How + Who)  │
│   ─────────────────────────    │   ───────────────────────────  │
│   • intention                  │   • orchestration              │
│   • success_criteria           │   • security                   │
│   • guardrails                 │   • files                      │
│   • capabilities               │   • integrity verification     │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📦 Installation

```bash
# Core kernel (zero dependencies)
npm install -g @josfox/jos

# With orchestration controller
npm install -g josctl

# With extended CLI features
npm install -g @josfox/jos-cli
```

---

## 🔧 Commands

| Command | Description |
|---------|-------------|
| `jos run <artifact>` | Execute a .jos artifact |
| `jos llm <artifact>` | Crystallize intention for LLM interaction |
| `jos validate <artifact>` | Strict validation (13 required keys) |
| `jos serve` | Launch local dashboard |
| `jos get <foxtail>` | Install artifact from registry |

---

## 📝 Minimal Valid Artifact

Every `.jos` artifact requires **13 keys** for strict validation:

```json
{
  "id_jos": "example-v1",
  "jos": { "open": "jos run artifact", "supports": ["@josfox/jos"] },
  "orchestration_contract": { "version": "0.0.7", "mode": "sync" },
  "meta": { "name": "example", "version": "1.0.0", "type": "atom" },
  "intention": { "objective": "Demonstrate JOS", "success_criteria": "Output greeting" },
  "guardrails": { "avoid": [], "max_retries": 0 },
  "capabilities": ["demo"],
  "artifacts": { "description": "Minimal example" },
  "orchestration": {
    "definitions": { "greet": { "type": "shell", "command": "echo 'Hello!'" } },
    "flows": { "main": { "steps": ["greet"] } }
  },
  "security": { "type": "open", "permissions": [], "integrity_ref": null },
  "files": [],
  "x_run_params": { "timeout": 5000, "retry_on_failure": false },
  "adaptive_ai": { "learning_enabled": false, "feedback_collection": false }
}
```

---

## 🔗 Ecosystem Links

| Resource | Link |
|----------|------|
| 📖 **Specification** | [github.com/josfox-ai/jos-format-spec](https://github.com/josfox-ai/jos-format-spec) |
| 🦊 **Starter Examples** | [github.com/josfox-ai/jos-repo-starter](https://github.com/josfox-ai/jos-repo-starter) |
| 🎨 **KRMEN Design System** | [krmen.mx](https://krmen.mx) |
| 📦 **npm: @josfox/jos** | [npmjs.com/package/@josfox/jos](https://www.npmjs.com/package/@josfox/jos) |
| 📦 **npm: josctl** | [npmjs.com/package/josctl](https://www.npmjs.com/package/josctl) |

---

## 🏛️ Governance

**JOS Open Standards Foundation**  
Specification v0.0.7 · Format v0.1.0 (Alpha)

---

## 📄 License

MIT © JOS Open Standards Foundation