agent-apprenticeship 0.2.1 → 0.3.0

package/README.md

@@ -1,17 +1,277 @@
+# Agent Apprenticeship
+
+[![npm version](https://img.shields.io/npm/v/agent-apprenticeship.svg)](https://www.npmjs.com/package/agent-apprenticeship)
+[![HF Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fhuggingface.co%2Fapi%2Fdatasets%2FForsy-AI%2Fagent-apprenticeship-seed-dataset&query=%24.downloads&label=HF%20downloads&logo=huggingface&color=yellow)](https://huggingface.co/datasets/rayrren/agent-apprenticeship-seed-dataset)
+
+**Real-world agent work experience, looped into collective learning.**
+
 The living ecosystem where AI agents complete tasks through workflow loops, improve through iterative execution, are evaluated by mentor agents or humans in the loop, and turn completed work into reusable work experience and data to improve future agents.
 
+```bash
+npx agent-apprenticeship init
+```
+
+![Agent Apprenticeship](apprenticeship.png)
+
 As agents move into long-horizon, economically valuable work, Agent Apprenticeship creates the open infrastructure where real-world tasks generate reusable learning signals and complex workflows advance through agent loops that turn execution into shared improvement.
 
 Agent Apprenticeship is designed for a compounding exchange of agent work experience: economically valuable task execution generates training signals, those signals improve future work, and future work creates new reusable experience for the ecosystem.
 
 Agent Apprenticeship is built for iterative workflow loops across domains, from simple tasks to complex specialized work. Apprentice agents work with mentor agents, users, or human experts to complete real-world tasks, while each workflow generates reusable learning signals for the ecosystem.
 
+The latest seed dataset includes:
+
+- 500+ curated seed tasks sourced and grounded from the real world
+- 495 reusable agent lessons
+- 1000+ full agent execution traces
+- 1000+ agent work episodes / task rollouts
+- 505 full agent work experience compilations
+- 39k+ structured experience compilation records
+
+The seed dataset spans specialized, economically valuable tasks across domains and forms the first layer of the Agent Apprenticeship ecosystem.
+
 Agent Apprenticeship is now available for anyone to start using with local agents, including Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent, and custom agents, alongside different model providers. Users can run automated agent workflow loops locally, contribute agent learning signals back to the ecosystem, and use shared ecosystem signals to improve their own agents.
 
 Agent Apprenticeship is about the future of work and the economic value of agents. For every task executed through Agent Apprenticeship, the system can estimate task-level economic value, especially across specialized domains. It is built for everyday use to improve agent performance and outcome quality, while enabling users to exchange agent work experience with each other and with domain-expert-led agents in one living ecosystem.
 
-## Quick Start
+## Install
+
+```bash
+npx agent-apprenticeship init
+```
+
+Or install globally:
+
+```bash
+npm install -g agent-apprenticeship
+apprentice init
+```
+
+The installed command is:
+
+```bash
+apprentice
+```
+
+The long-form command also remains available:
+
+```bash
+agent-apprenticeship
+```
+
+## Quickstart
+
+Start Agent Apprenticeship:
 
 ```bash
 npx agent-apprenticeship init
 ```
+
+Use defaults:
+
+```bash
+npx agent-apprenticeship init --defaults
+```
+
+Check your setup:
+
+```bash
+apprentice settings
+apprentice doctor
+```
+
+Configure your Apprentice Agent, Mentor Model Provider, and Apprenticeship Mode:
+
+```bash
+apprentice configure
+apprentice configure model
+apprentice settings
+```
+
+Apprenticeship Modes:
+
+```text
+Autonomous
+Expert-Led
+Organization Custom
+```
+
+Store Mentor Model Provider keys in:
+
+```bash
+~/.agent-apprenticeship/.env.local
+```
+
+Example:
+
+```bash
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+OPENROUTER_API_KEY=""
+```
+
+You can also use shell environment variables for the current terminal session:
+
+```bash
+export OPENAI_API_KEY="..."
+apprentice doctor
+```
+
+Run your first task:
+
+```bash
+apprentice run "Create a short market map for AI procurement tools."
+```
+
+Watch progress:
+
+```bash
+apprentice watch <run_id>
+```
+
+When the run completes, Agent Apprenticeship prints the local run folder and Experience Compilation path.
+
+Inspect the generated Experience Compilation:
+
+```bash
+apprentice ecosystem inspect <experience_compilation_path>
+apprentice bundle check <experience_compilation_path>
+```
+
+Export the Full Experience Compilation:
+
+```bash
+apprentice ecosystem export <experience_compilation_path> --full
+```
+
+Install Runtime Training from prior experience:
+
+```bash
+apprentice learn install <experience_compilation_path>
+```
+
+Use installed Runtime Training in a future run:
+
+```bash
+apprentice run "Create a release checklist for an AI agent project."
+```
+
+Configure maximum loop depth:
+
+```bash
+apprentice settings
+```
+
+For a one-off terminal session:
+
+```bash
+export AA_MAX_ITERATIONS=3
+```
+
+## Apprentice Agents
+
+Available Apprentice Agents:
+
+```text
+Codex
+Cursor
+Claude Code
+OpenClaw
+OpenCode
+Hermes Agent
+Custom
+```
+
+Agent Apprenticeship auto-detects installed CLIs. If multiple are detected, choose one during setup.
+
+Custom lets you provide a command template:
+
+```bash
+apprentice configure agent custom --command-template "my-agent run --workspace {workspace} --prompt-file {prompt_file}"
+```
+
+## Mentor Model Providers
+
+Store local keys in:
+
+```bash
+~/.agent-apprenticeship/.env.local
+```
+
+Example:
+
+```bash
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+OPENROUTER_API_KEY=""
+```
+
+Configure:
+
+```bash
+apprentice configure model
+apprentice doctor
+```
+
+## Public Ecosystem and Private Internal Only
+
+Configure contribution mode:
+
+```bash
+apprentice settings
+```
+
+Modes:
+
+```text
+Public Ecosystem
+Private Internal Only
+```
+
+Explore ecosystem experience:
+
+```bash
+apprentice ecosystem search <query>
+apprentice ecosystem inspect <id>
+apprentice ecosystem pull <id>
+```
+
+Export Full Experience Compilation:
+
+```bash
+apprentice ecosystem export <id_or_path> --full
+```
+
+Install Runtime Training:
+
+```bash
+apprentice learn install <id_or_path>
+```
+
+## Seed Dataset v0.2
+
+Seed Dataset v0.2 is available on Hugging Face:
+
+https://huggingface.co/datasets/Forsy-AI/agent-apprenticeship-seed-dataset_v0.2
+
+It includes 505 full agent work experience compilations and 39k+ structured experience compilation records.
+
+## Selected ALE Tasks Demo
+
+Selected ALE workflow-family mirrored transfer tasks are included under:
+
+```text
+selected_ale_tasks_demo/
+```
+
+## Public Repo Structure
+
+```text
+bin/
+src/
+schemas/
+examples/
+selected_ale_tasks_demo/
+```

package/bin/agent-apprenticeship.js

@@ -274,7 +274,6 @@ async function ensureRuntime(python) {
       "--disable-pip-version-check",
       "--progress-bar", "off",
       "--no-input",
-      "--no-build-isolation",
       "--retries", "10",
       "--timeout", "60",
       packageRoot
@@ -297,7 +296,7 @@ function runCli(python, args, usePackagedSource) {
     const srcPath = path.join(packageRoot, "src");
     env.PYTHONPATH = env.PYTHONPATH ? `${srcPath}${path.delimiter}${env.PYTHONPATH}` : srcPath;
   }
-  const result = spawnSync(python, ["-m", "agent_apprenticeship_trace.cli", ...args], {
+  const result = spawnSync(python, ["-m", "agent_apprenticeship.cli", ...args], {
     stdio: "inherit",
     env
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-apprenticeship",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The living ecosystem for AI agents learning from real-world work through iterative loops and training-signal exchange.",
   "license": "MIT",
   "repository": {
@@ -14,13 +14,13 @@
   "files": [
     "README.md",
     "LICENSE",
-    "docs",
+    "schemas",
     "pyproject.toml",
-    "src/agent_apprenticeship_trace",
+    "src/agent_apprenticeship",
     "bin"
   ],
   "scripts": {
-    "test": ".venv/bin/python -m pytest -q tests",
+    "test": "python -m pytest -q tests",
     "pack": "npm pack --dry-run",
     "prepack": "find src bin -name __pycache__ -type d -prune -exec rm -rf {} + && find src bin -name '*.pyc' -delete",
     "smoke": "PATH=./.venv/bin:$PATH AA_NPM_USE_SYSTEM_PYTHON=1 node ./bin/agent-apprenticeship.js --help"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-apprenticeship"
-version = "0.2.1"
+version = "0.3.0"
 description = "Open framework for turning real agent work into transferable agent experience"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -15,9 +15,15 @@ llm = ["openai>=2,<3"]
 test = ["pytest>=8"]
 
 [project.scripts]
-apprentice = "agent_apprenticeship_trace.cli:main"
-agent-apprenticeship = "agent_apprenticeship_trace.cli:main"
-aa-trace = "agent_apprenticeship_trace.cli:main"
+apprentice = "agent_apprenticeship.cli:main"
+agent-apprenticeship = "agent_apprenticeship.cli:main"
+aa-trace = "agent_apprenticeship.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+"agent_apprenticeship.atif_models" = ["LICENSE"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

package/schemas/environment_replay.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forsy.ai/schemas/agent-apprenticeship/environment_replay.schema.json",
+  "title": "Environment Replay",
+  "type": "object",
+  "required": ["environment_id", "task_id", "action_schema", "observation_schema", "state_transitions"],
+  "properties": {
+    "environment_id": { "type": "string", "minLength": 1 },
+    "task_id": { "type": "string", "minLength": 1 },
+    "dependency_spec": { "type": "object" },
+    "tool_spec": { "type": "object" },
+    "action_schema": { "type": "object" },
+    "observation_schema": { "type": "object" },
+    "state_transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["transition_id", "action", "observation"],
+        "properties": {
+          "transition_id": { "type": "string" },
+          "action": { "type": "object" },
+          "observation": { "type": "object" },
+          "artifact_deltas": {
+            "type": "array",
+            "items": { "type": "object" }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "reward_components": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "source_evidence_refs": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/eval_package.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forsy.ai/schemas/agent-apprenticeship/eval_package.schema.json",
+  "title": "Evaluation Package",
+  "type": "object",
+  "required": ["eval_package_id", "task_id", "rubric_items", "verifier_cases"],
+  "properties": {
+    "eval_package_id": { "type": "string", "minLength": 1 },
+    "task_id": { "type": "string", "minLength": 1 },
+    "rubric_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["rubric_item_id", "criterion", "weight"],
+        "properties": {
+          "rubric_item_id": { "type": "string" },
+          "criterion": { "type": "string" },
+          "weight": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": true
+      }
+    },
+    "verifier_cases": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "expected_artifacts": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "source_evidence_refs": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/experience_compilation.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forsy.ai/schemas/agent-apprenticeship/experience_compilation.schema.json",
+  "title": "Experience Compilation",
+  "type": "object",
+  "required": [
+    "compilation_id",
+    "title",
+    "task_title",
+    "schema_version",
+    "compiler_version",
+    "package_version",
+    "created_at",
+    "components"
+  ],
+  "properties": {
+    "compilation_id": { "type": "string", "minLength": 1 },
+    "title": { "type": "string", "minLength": 1 },
+    "task_title": { "type": "string", "minLength": 1 },
+    "domain": { "type": "string" },
+    "subdomain": { "type": "string" },
+    "workflow_family": { "type": "string" },
+    "schema_version": { "type": "string", "minLength": 1 },
+    "compiler_version": { "type": "string", "minLength": 1 },
+    "package_version": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "training_row_counts": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "components": {
+      "type": "object",
+      "required": [
+        "traces",
+        "runtime_training",
+        "training_time_package",
+        "eval_package",
+        "environment_replay",
+        "source_evidence_map"
+      ],
+      "properties": {
+        "traces": { "type": "boolean" },
+        "runtime_training": { "type": "boolean" },
+        "training_time_package": { "type": "boolean" },
+        "eval_package": { "type": "boolean" },
+        "environment_replay": { "type": "boolean" },
+        "source_evidence_map": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/runtime_training.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forsy.ai/schemas/agent-apprenticeship/runtime_training.schema.json",
+  "title": "Runtime Training",
+  "type": "object",
+  "required": [
+    "runtime_training_id",
+    "source_compilation_id",
+    "title",
+    "confidence",
+    "minimal_prompt_context",
+    "output_contract",
+    "artifact_contract"
+  ],
+  "properties": {
+    "runtime_training_id": { "type": "string", "minLength": 1 },
+    "source_compilation_id": { "type": "string", "minLength": 1 },
+    "title": { "type": "string", "minLength": 1 },
+    "confidence": { "type": "string", "enum": ["low", "medium", "high", "unknown"] },
+    "minimal_prompt_context": { "type": "string", "minLength": 1 },
+    "output_contract": { "type": "object" },
+    "artifact_contract": { "type": "object" },
+    "prefinal_verification_checklist": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "source_evidence_refs": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/source_evidence_map.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forsy.ai/schemas/agent-apprenticeship/source_evidence_map.schema.json",
+  "title": "Source Evidence Map",
+  "type": "object",
+  "required": ["evidence_ref", "source_type", "evidence_kind", "visibility", "confidence"],
+  "properties": {
+    "evidence_ref": { "type": "string", "minLength": 1 },
+    "source_type": {
+      "type": "string",
+      "enum": ["trace", "trace_step", "artifact", "actual_output", "review_packet", "verifier_record", "grader_record", "repair_record", "manifest", "generated_row"]
+    },
+    "evidence_kind": { "type": "string", "minLength": 1 },
+    "visibility": { "type": "string", "enum": ["visible", "inferred", "generated"] },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "source_id": { "type": "string" },
+    "source_path": { "type": "string" },
+    "source_content_hash": { "type": "string" },
+    "row_refs": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}