@agent-e/core 1.5.6 → 1.5.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +110 -132
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
- # @agent-e/core
1
+ # AgentE — Autonomous Economic Balancer
2
2
 
3
- Autonomous economic balancer SDK. 60 built-in principles, 5-stage pipeline, zero dependencies. Works with any digital economy.
3
+ > 60 principles. 5-stage pipeline. One npm install. Any economy.
4
+
5
+ AgentE observes, diagnoses, simulates, plans, and executes — keeping any digital economy healthy without manual tuning. If it has currencies, resources, and participants, AgentE balances it.
4
6
 
5
7
  ## Install
6
8
 
@@ -15,187 +17,163 @@ import { AgentE } from '@agent-e/core';
15
17
 
16
18
  const agent = new AgentE({
17
19
  adapter: {
20
+ // AgentE calls this every tick.
21
+ // Return a snapshot of your economy — from YOUR database/API.
18
22
  getState: () => ({
19
- tick: currentTick,
20
- currencies: ['currency_a', 'currency_b'],
21
- systems: ['system_1', 'system_2'],
22
- agentBalances: {
23
- agent_001: { currency_a: 500, currency_b: 20 },
24
- agent_002: { currency_a: 120, currency_b: 80 },
25
- },
26
- agentRoles: { agent_001: 'role_a', agent_002: 'role_b' },
27
- marketPrices: {
28
- currency_a: { resource_x: 10, resource_y: 25 },
29
- },
30
- agentSatisfaction: { agent_001: 72, agent_002: 85 },
31
- poolSizes: { main_pool: { currency_a: 5000 } },
32
- roles: ['role_a', 'role_b'],
33
- resources: ['resource_x', 'resource_y'],
34
- recentTransactions: [],
23
+ tick: getCurrentTick(),
24
+ currencies: getCurrencies(), // e.g. ['gold', 'gems']
25
+ systems: getSystems(), // e.g. ['crafting', 'arena']
26
+ roles: getRoles(), // e.g. ['warrior', 'merchant']
27
+ resources: getResources(), // e.g. ['ore', 'wood']
28
+ agentBalances: getBalances(), // agent → currency → amount
29
+ agentRoles: getAgentRoles(), // agent → role
30
+ marketPrices: getPrices(), // currency → resource → price
31
+ recentTransactions: getTxns(),
35
32
  }),
33
+
34
+ // AgentE tells you WHAT to change — you apply it
36
35
  setParam: async (param, value, scope) => {
37
36
  applyToYourEconomy(param, value, scope);
38
37
  },
39
38
  },
39
+
40
+ // Register YOUR economy's tunable parameters
40
41
  parameters: [
41
- { key: 'your_fee_param', type: 'fee', flowImpact: 'friction', scope: { system: 'system_1' } },
42
- { key: 'your_reward_param', type: 'reward', flowImpact: 'faucet', scope: { system: 'system_2' } },
42
+ { key: 'crafting_cost', type: 'cost', flowImpact: 'sink' },
43
+ { key: 'arena_reward', type: 'reward', flowImpact: 'faucet' },
44
+ { key: 'market_fee', type: 'fee', flowImpact: 'friction' },
43
45
  ],
46
+
44
47
  mode: 'advisor',
48
+ onDecision: (d) => console.log(d),
45
49
  });
46
50
 
47
51
  agent.start();
52
+
53
+ // In your loop:
48
54
  await agent.tick();
49
55
  ```
50
56
 
51
- **Replace the placeholder names with YOUR economy's actual names.** See the root README for real-world examples (game, DeFi, marketplace).
52
-
53
- ## The 5-Stage Pipeline
57
+ > **You never hand-type agents.** `getState()` pulls from your existing backend — whether that's 50 players or 5 million. AgentE computes aggregate metrics (Gini, velocity, flow rates) and balances the economy as a whole.
54
58
 
55
- 1. **Observer** — Translates raw state into 40+ metrics at 3 resolutions (fine/medium/coarse)
56
- 2. **Diagnoser** — Runs 60 principles, returns violations sorted by severity
57
- 3. **Simulator** — Monte Carlo forward projection (≥100 iterations) before any action
58
- 4. **Planner** — Lag-aware, cooldown-aware planning with rollback conditions
59
- 5. **Executor** — Applies actions and monitors for rollback triggers
59
+ ## What Does That Look Like in Practice?
60
60
 
61
- ## Parameter Registry
61
+ The Quick Start above uses placeholder names. Here's what real setups look like:
62
62
 
63
- Register your parameters with semantic types and flow impacts:
63
+ ### Game Economy
64
64
 
65
65
  ```typescript
66
+ currencies: ['gold', 'gems'],
67
+ systems: ['crafting', 'arena', 'marketplace'],
66
68
  parameters: [
67
- // key: whatever YOU call it
68
- // type: what kind of lever is it?
69
- // flowImpact: what does it do to currency flow?
70
- // scope: where in your economy does it live?
71
-
72
- { key: 'my_fee', type: 'fee', flowImpact: 'friction', scope: { system: 'trading' } },
73
- { key: 'my_reward', type: 'reward', flowImpact: 'faucet', scope: { system: 'engagement' } },
74
- { key: 'my_rate', type: 'rate', flowImpact: 'sink', scope: { system: 'burning' } },
75
- { key: 'my_yield', type: 'yield', flowImpact: 'faucet', scope: { system: 'staking', currency: 'currency_b' } },
76
- { key: 'my_cut', type: 'fee', flowImpact: 'sink', scope: { system: 'platform', tags: ['operator'] } },
77
- ]
69
+ { key: 'craftingCost', type: 'cost', flowImpact: 'sink', scope: { system: 'crafting' } },
70
+ { key: 'arenaReward', type: 'reward', flowImpact: 'faucet', scope: { system: 'arena' } },
71
+ { key: 'auctionFee', type: 'fee', flowImpact: 'friction', scope: { system: 'marketplace' } },
72
+ ],
78
73
  ```
79
74
 
80
- Principles say "decrease `fee` in `trading`" — the registry resolves to `my_fee`. Your names stay yours.
81
-
82
- ### Semantic Types
75
+ ### DeFi Protocol (Coming Soon)
83
76
 
84
- | Type | What it means |
85
- |------|--------------|
86
- | `cost` | Something participants pay to do an action |
87
- | `fee` | A percentage or flat charge on transactions |
88
- | `reward` | Something participants receive for an action |
89
- | `yield` | Passive income from holding or staking |
90
- | `rate` | A speed or frequency multiplier |
91
- | `multiplier` | A scaling factor |
92
- | `threshold` | A boundary value that triggers behavior |
93
- | `weight` | A relative importance factor |
94
- | `custom` | Anything else |
77
+ ```typescript
78
+ currencies: ['ETH', 'USDC'],
79
+ systems: ['amm', 'lending', 'staking'],
80
+ parameters: [
81
+ { key: 'swapFee', type: 'fee', flowImpact: 'friction', scope: { system: 'amm' } },
82
+ { key: 'borrowRate', type: 'rate', flowImpact: 'sink', scope: { system: 'lending' } },
83
+ { key: 'stakingYield', type: 'yield', flowImpact: 'faucet', scope: { system: 'staking' } },
84
+ ],
85
+ ```
95
86
 
96
- ### Flow Impacts
87
+ ### Marketplace (Coming Soon)
97
88
 
98
- | Impact | What it does to currency flow |
99
- |--------|------------------------------|
100
- | `sink` | Removes currency from circulation |
101
- | `faucet` | Adds currency to circulation |
102
- | `friction` | Slows velocity without removing currency |
103
- | `redistribution` | Moves currency between participants |
104
- | `neutral` | No direct effect on flow |
89
+ ```typescript
90
+ currencies: ['credits'],
91
+ systems: ['listings', 'promotions', 'referrals'],
92
+ parameters: [
93
+ { key: 'listingFee', type: 'fee', flowImpact: 'friction', scope: { system: 'listings' } },
94
+ { key: 'promoDiscount', type: 'cost', flowImpact: 'faucet', scope: { system: 'promotions' } },
95
+ { key: 'referralBonus', type: 'reward', flowImpact: 'faucet', scope: { system: 'referrals' } },
96
+ ],
97
+ ```
105
98
 
106
- ## Multi-System, Multi-Currency
99
+ **The parameter names are YOURS. AgentE only cares about the `type` and `flowImpact`.**
107
100
 
108
- AgentE tracks each system and currency independently:
101
+ ## How It Works
109
102
 
110
- - Per-currency: supply, net flow, velocity, inflation, Gini, wealth distribution, faucet/sink volumes, price index
111
- - Per-system: flow, activity, participant count
112
- - Cross-system: arbitrage index, source/sink share analysis
103
+ ```
104
+ Your Economy → Observer → Diagnoser → Simulator → Planner → Executor → Your Economy
105
+ ```
113
106
 
114
- ## Modes
107
+ 1. **Observer** — computes 40+ metrics at 3 time resolutions (fine/medium/coarse)
108
+ 2. **Diagnoser** — runs 60 principles, returns violations sorted by severity
109
+ 3. **Simulator** — Monte Carlo forward projection (≥100 iterations) before any action
110
+ 4. **Planner** — lag-aware, cooldown-aware action planning with rollback conditions
111
+ 5. **Executor** — applies actions, monitors for rollback triggers
115
112
 
116
- | Mode | Behavior |
117
- |------|----------|
118
- | `autonomous` | Full pipeline — executes parameter changes automatically |
119
- | `advisor` | Full pipeline but stops before execution — emits recommendations via `onDecision` |
113
+ ## Universal by Design
120
114
 
121
- ## Developer API
115
+ AgentE is not a game tool, a DeFi tool, or a marketplace tool. It's an **economy tool**. The core SDK has zero domain-specific logic.
122
116
 
123
- ```typescript
124
- // Lock — AgentE will never adjust this parameter
125
- agent.lock('your_param_name');
126
- agent.unlock('your_param_name');
117
+ ### Parameter Registry
127
118
 
128
- // Constrain — AgentE can adjust, but only within this range
129
- agent.constrain('another_param', { min: 0.01, max: 0.50 });
119
+ The core innovation. You register YOUR parameters with semantic metadata:
130
120
 
131
- // Add a custom principle
132
- agent.addPrinciple(myPrinciple);
121
+ - **`type`** — what kind of lever is it? (`cost`, `fee`, `reward`, `yield`, `rate`, `multiplier`, `threshold`, `weight`, `custom`)
122
+ - **`flowImpact`** — what does it do to the flow of currency? (`sink`, `faucet`, `friction`, `redistribution`, `neutral`)
123
+ - **`scope`** — where in your economy does it live? (`{ system?, currency?, tags? }`)
133
124
 
134
- // Register a custom metric
135
- agent.registerCustomMetric('myMetric', (state) => compute(state));
125
+ AgentE's 60 principles target **types**, not names. When a principle says "decrease the `fee` in `system_1`", the registry resolves that to YOUR parameter name.
136
126
 
137
- // Veto actions
138
- agent.on('beforeAction', (plan) => {
139
- if (plan.parameterType === 'reward') return false;
140
- });
127
+ ### Multi-Everything
141
128
 
142
- // Query decision history
143
- const decisions = agent.getDecisions({ outcome: 'applied' });
129
+ - **Multi-System** — register multiple sub-systems, each tracked independently
130
+ - **Multi-Currency** — every currency gets its own supply, velocity, Gini, inflation, faucet/sink metrics
131
+ - **Multi-Resource** — track resources, roles, pools, and market prices across the economy
132
+ - **Opt-in** — only register what your economy has. No pools? Don't register pool parameters. AgentE won't touch what doesn't exist.
144
133
 
145
- // Health score (0-100)
146
- const health = agent.getHealth();
134
+ ## Modes
147
135
 
148
- // Metric time-series
149
- const latest = agent.metrics.latest('fine');
150
- ```
136
+ | Mode | What happens |
137
+ |------|-------------|
138
+ | `autonomous` | Full pipeline — observes, diagnoses, simulates, plans, executes automatically |
139
+ | `advisor` | Full pipeline but stops before execution — emits recommendations for your approval |
151
140
 
152
- ## Custom Principles
141
+ ## Developer Controls
153
142
 
154
143
  ```typescript
155
- import type { Principle } from '@agent-e/core';
156
-
157
- const myRule: Principle = {
158
- id: 'MY_01',
159
- name: 'Minimum Provider Population',
160
- category: 'population',
161
- description: 'Triggers when a critical role drops below 5% of population',
162
- check(metrics, thresholds) {
163
- const share = metrics.roleShares['role_a'] ?? 0;
164
- if (share < 0.05) {
165
- return {
166
- violated: true,
167
- severity: 8,
168
- evidence: { share },
169
- suggestedAction: {
170
- parameterType: 'reward',
171
- scope: { tags: ['role_a'] },
172
- direction: 'increase',
173
- magnitude: 0.25,
174
- reasoning: 'Critical role population below 5%.',
175
- },
176
- confidence: 0.90,
177
- estimatedLag: 10,
178
- };
179
- }
180
- return { violated: false };
181
- },
182
- };
144
+ // Lock a parameter — AgentE will NEVER adjust it
145
+ agent.lock('your_param_name');
146
+
147
+ // Constrain a parameter to a range — AgentE can adjust it, but only within these bounds
148
+ agent.constrain('another_param', { min: 0.5, max: 2.0 });
149
+
150
+ // Add your own principle
151
+ agent.addPrinciple(myCustomPrinciple);
183
152
 
184
- agent.addPrinciple(myRule);
153
+ // Veto specific actions before they execute
154
+ agent.on('beforeAction', (plan) => {
155
+ if (plan.parameterType === 'reward' && plan.direction === 'increase') return false;
156
+ });
185
157
  ```
186
158
 
187
159
  ## 60 Principles
188
160
 
189
- Organized across 15 categories: supply chain, incentives, population, currency flow, bootstrap, feedback loops, regulator, market dynamics, measurement, statistical, system dynamics, resource management, participant experience, open economy, and operations.
161
+ Built-in knowledge base across 15 categories: supply chain, incentives, population, currency flow, bootstrap, feedback loops, regulator, market dynamics, measurement, statistical, system dynamics, resource management, participant experience, open economy, and operations.
162
+
163
+ Each principle returns either `{ violated: false }` or a full violation with severity, evidence, suggested action (parameterType + scope), confidence score, and estimated lag.
164
+
165
+ ## Packages
190
166
 
191
- ## Performance
167
+ | Package | Description |
168
+ |---------|-------------|
169
+ | `@agent-e/core` | The SDK. Zero dependencies. |
170
+ | `@agent-e/adapter-game` | Presets for game economies |
171
+ | `@agent-e/server` | HTTP + WebSocket server for game engine integration |
192
172
 
193
- - **O(N) event classification** — single-pass instead of 6 separate filters
194
- - **O(n) arbitrage index** — log-price standard deviation instead of pairwise
195
- - **Cached diagnosis** — no redundant principle checks within the same tick
196
- - **Numerical stability** — clamped inputs to prevent NaN/Infinity edge cases
173
+ ## Links
197
174
 
198
- Typical for 1,000 agents, 100 events/tick: ~60ms end-to-end.
175
+ - [npm](https://www.npmjs.com/package/@agent-e/core)
176
+ - [GitHub](https://github.com/AE-Vault/AgentE)
199
177
 
200
178
  ## License
201
179
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-e/core",
3
- "version": "1.5.6",
3
+ "version": "1.5.8",
4
4
  "description": "Autonomous economic balancer SDK — observe, diagnose, simulate, plan, execute. Any digital economy.",
5
5
  "license": "MIT",
6
6
  "repository": {