@agent-e/core 1.5.2 → 1.5.3

package/README.md

@@ -1,6 +1,6 @@
 # @agent-e/core
 
-Autonomous economic balancer SDK. 60 built-in principles, 5-stage pipeline, zero dependencies. Works with any digital economy — games, DeFi, marketplaces, token systems, social platforms.
+Autonomous economic balancer SDK. 60 built-in principles, 5-stage pipeline, zero dependencies. Works with any digital economy.
 
 ## Install
 
@@ -17,20 +17,20 @@ const agent = new AgentE({
   adapter: {
     getState: () => ({
       tick: currentTick,
-      currencies: ['credits', 'tokens'],
-      systems: ['exchange', 'rewards'],
+      currencies: ['currency_a', 'currency_b'],
+      systems: ['system_1', 'system_2'],
       agentBalances: {
-        user_a: { credits: 500, tokens: 20 },
-        user_b: { credits: 300, tokens: 80 },
+        agent_001: { currency_a: 500, currency_b: 20 },
+        agent_002: { currency_a: 120, currency_b: 80 },
       },
-      agentRoles: { user_a: 'provider', user_b: 'consumer' },
+      agentRoles: { agent_001: 'role_a', agent_002: 'role_b' },
       marketPrices: {
-        credits: { service_a: 10, service_b: 25 },
+        currency_a: { resource_x: 10, resource_y: 25 },
       },
-      agentSatisfaction: { user_a: 72, user_b: 85 },
-      poolSizes: { rewardPool: { credits: 5000 } },
-      roles: ['provider', 'consumer'],
-      resources: ['service_a', 'service_b'],
+      agentSatisfaction: { agent_001: 72, agent_002: 85 },
+      poolSizes: { main_pool: { currency_a: 5000 } },
+      roles: ['role_a', 'role_b'],
+      resources: ['resource_x', 'resource_y'],
       recentTransactions: [],
     }),
     setParam: async (param, value, scope) => {
@@ -38,8 +38,8 @@ const agent = new AgentE({
     },
   },
   parameters: [
-    { key: 'exchangeFee', type: 'fee', flowImpact: 'friction', scope: { system: 'exchange' } },
-    { key: 'dailyReward', type: 'reward', flowImpact: 'faucet', scope: { system: 'rewards' } },
+    { key: 'your_fee_param',    type: 'fee',    flowImpact: 'friction', scope: { system: 'system_1' } },
+    { key: 'your_reward_param', type: 'reward', flowImpact: 'faucet',   scope: { system: 'system_2' } },
   ],
   mode: 'advisor',
 });
@@ -48,6 +48,8 @@ agent.start();
 await agent.tick();
 ```
 
+**Replace the placeholder names with YOUR economy's actual names.** See the root README for real-world examples (game, DeFi, marketplace).
+
 ## The 5-Stage Pipeline
 
 1. **Observer** — Translates raw state into 40+ metrics at 3 resolutions (fine/medium/coarse)
@@ -58,19 +60,48 @@ await agent.tick();
 
 ## Parameter Registry
 
-Register your economy's parameters with semantic types and flow impacts:
+Register your parameters with semantic types and flow impacts:
 
 ```typescript
 parameters: [
-  { key: 'tradeFee',   type: 'fee',    flowImpact: 'friction',       scope: { system: 'trading' } },
-  { key: 'mintReward', type: 'reward', flowImpact: 'faucet',         scope: { system: 'minting' } },
-  { key: 'burnRate',   type: 'rate',   flowImpact: 'sink',           scope: { system: 'burning' } },
-  { key: 'lpYield',    type: 'yield',  flowImpact: 'faucet',         scope: { system: 'liquidity', currency: 'tokens' } },
-  { key: 'platformCut', type: 'fee',   flowImpact: 'sink',           scope: { system: 'marketplace', tags: ['operator'] } },
+  // key: whatever YOU call it
+  // type: what kind of lever is it?
+  // flowImpact: what does it do to currency flow?
+  // scope: where in your economy does it live?
+
+  { key: 'my_fee',      type: 'fee',      flowImpact: 'friction',       scope: { system: 'trading' } },
+  { key: 'my_reward',   type: 'reward',   flowImpact: 'faucet',         scope: { system: 'engagement' } },
+  { key: 'my_rate',     type: 'rate',     flowImpact: 'sink',           scope: { system: 'burning' } },
+  { key: 'my_yield',    type: 'yield',    flowImpact: 'faucet',         scope: { system: 'staking', currency: 'currency_b' } },
+  { key: 'my_cut',      type: 'fee',      flowImpact: 'sink',           scope: { system: 'platform', tags: ['operator'] } },
 ]
 ```
 
-Principles target types (e.g., "decrease `fee` in `trading`"), and the registry resolves to your concrete parameter name.
+Principles say "decrease `fee` in `trading`" — the registry resolves to `my_fee`. Your names stay yours.
+
+### Semantic Types
+
+| Type | What it means |
+|------|--------------|
+| `cost` | Something participants pay to do an action |
+| `fee` | A percentage or flat charge on transactions |
+| `reward` | Something participants receive for an action |
+| `yield` | Passive income from holding or staking |
+| `rate` | A speed or frequency multiplier |
+| `multiplier` | A scaling factor |
+| `threshold` | A boundary value that triggers behavior |
+| `weight` | A relative importance factor |
+| `custom` | Anything else |
+
+### Flow Impacts
+
+| Impact | What it does to currency flow |
+|--------|------------------------------|
+| `sink` | Removes currency from circulation |
+| `faucet` | Adds currency to circulation |
+| `friction` | Slows velocity without removing currency |
+| `redistribution` | Moves currency between participants |
+| `neutral` | No direct effect on flow |
 
 ## Multi-System, Multi-Currency
 
@@ -90,12 +121,12 @@ AgentE tracks each system and currency independently:
 ## Developer API
 
 ```typescript
-// Lock a parameter from automated adjustment
-agent.lock('exchangeFee');
-agent.unlock('exchangeFee');
+// Lock — AgentE will never adjust this parameter
+agent.lock('your_param_name');
+agent.unlock('your_param_name');
 
-// Constrain a parameter to a range
-agent.constrain('dailyReward', { min: 1, max: 100 });
+// Constrain — AgentE can adjust, but only within this range
+agent.constrain('another_param', { min: 0.01, max: 0.50 });
 
 // Add a custom principle
 agent.addPrinciple(myPrinciple);
@@ -125,11 +156,11 @@ import type { Principle } from '@agent-e/core';
 
 const myRule: Principle = {
   id: 'MY_01',
-  name: 'Provider Population Floor',
+  name: 'Minimum Provider Population',
   category: 'population',
-  description: 'Provider role share below 5% is a crisis',
+  description: 'Triggers when a critical role drops below 5% of population',
   check(metrics, thresholds) {
-    const share = metrics.roleShares['provider'] ?? 0;
+    const share = metrics.roleShares['role_a'] ?? 0;
     if (share < 0.05) {
       return {
         violated: true,
@@ -137,10 +168,10 @@ const myRule: Principle = {
         evidence: { share },
         suggestedAction: {
           parameterType: 'reward',
-          scope: { tags: ['provider'] },
+          scope: { tags: ['role_a'] },
           direction: 'increase',
           magnitude: 0.25,
-          reasoning: 'Provider population critically low.',
+          reasoning: 'Critical role population below 5%.',
         },
         confidence: 0.90,
         estimatedLag: 10,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-e/core",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Autonomous economic balancer SDK — observe, diagnose, simulate, plan, execute. Any digital economy.",
   "license": "MIT",
   "repository": {