@openclawcity/become 0.1.0 → 0.2.0

package/README.md

@@ -1,132 +1,185 @@
-# @openclaw/become
+<div align="center">
 
-**Agents get smarter together.**
+# become
 
-An open-source framework for multi-agent evolutionary learning. Track skills, measure growth, and enable agents to learn from each other.
+### Get your agents talking to other agents. They learn and evolve.
 
-## Two ways agents learn
+Two agents have a conversation. One teaches the other something.
+**become** extracts that lesson and injects it into the learner's context.
+Next time that agent acts, it's smarter. That's it.
 
-**From their humans** — every conversation is a learning signal. Good responses reinforce skills. Failed responses generate corrective ones.
+<br>
 
-**From each other** — peer review, collaboration, observation, teaching. When one agent masters a skill, others learn from its work. The whole group gets smarter.
+[![npm version](https://img.shields.io/npm/v/@openclawcity/become?style=flat&labelColor=555&color=22d3ee)](https://www.npmjs.com/package/@openclawcity/become)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat&labelColor=555)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-396_passing-22d3ee?style=flat&labelColor=555)]()
 
-## Quickstart
+</div>
+
+---
+
+## How it works
+
+```typescript
+import { AgentLearningEngine, MemoryStore } from '@openclawcity/become';
+
+const store = new MemoryStore();
+const engine = new AgentLearningEngine(store, yourLLM);
+
+// Two agents had a conversation
+await engine.learnFromConversation({
+  agent_a: 'agent-1',
+  agent_b: 'agent-2',
+  messages: [
+    { from: 'agent-2', text: 'You should use IEEE citation format for papers' },
+    { from: 'agent-1', text: 'Thanks! Your pie chart would work better as a bar chart for that data' },
+  ],
+});
+
+// Now get what each agent learned — inject this into their next prompt
+const context1 = await engine.getContext('agent-1');
+// "Based on your interactions with other agents, you have learned:
+//  - Use IEEE citation format for research papers (from a conversation)"
+
+const context2 = await engine.getContext('agent-2');
+// "Based on your interactions with other agents, you have learned:
+//  - Use bar charts instead of pie charts for categorical comparisons (from a conversation)"
+```
+
+That's the full loop. Two agents talk → become extracts lessons → lessons get injected into each agent's context → agents are smarter next time they act.
+
+---
+
+## Install
 
 ```bash
-npm install @openclaw/become
+npm install @openclawcity/become
 ```
 
-```typescript
-import { Become, MemoryStore } from '@openclaw/become';
-import { computeFullScore } from '@openclaw/become';
+---
 
-// 1. Initialize
-const become = new Become({ store: new MemoryStore() });
+## What actually happens
 
-// 2. Register a skill
-await become.skills.upsert('agent-1', {
-  name: 'debugging',
-  category: 'coding',
-});
+1. **Two agents have a conversation** — chat, collaboration, peer review, any exchange
+2. **become analyzes the conversation** (via your LLM) and extracts concrete, actionable lessons for each agent
+3. **Lessons are persisted** — they don't disappear when the conversation ends
+4. **You call `getContext(agentId)`** and get a text block of everything that agent has learned from other agents
+5. **You include that text in the agent's system prompt** — now the agent follows those instructions
+6. **The agent acts differently** — it uses IEEE citations, it avoids pie charts, it structures code better. Whatever it learned.
 
-// 3. Score it based on evidence
-const score = computeFullScore('debugging', {
-  artifact_count: 5,
-  total_reactions: 12,
-  recent_reaction_avg: 4,
-  older_reaction_avg: 2,
-  unique_types: 3,
-  collab_count: 1,
-  peer_reviews_given: 0,
-  peer_reviews_received: 1,
-  follower_count: 2,
-  teaching_events: 0,
-});
+The more agents talk to each other, the more each agent knows. The more agents in the system, the faster everyone learns.
+
+---
+
+## Peer reviews are the strongest signal
 
-console.log(score.score);         // 28
-console.log(score.dreyfus_stage); // 'beginner'
-console.log(score.blooms_level);  // 'analyze'
+When one agent reviews another's work, the feedback is explicit and structured. become extracts lessons directly from weaknesses and suggestions:
 
-// 4. Reflect on growth
-await become.reflector.reflect('agent-1', {
-  skill: 'debugging',
-  reflection: 'Print statements help me trace issues faster than step-through debugging.',
+```typescript
+const lessons = await engine.learnFromPeerReview({
+  reviewer: 'any-agent-123',
+  reviewee: 'my-agent',
+  assessment: 'Solid methodology but missing control group and literature review is misplaced.',
+  strengths: ['clear hypothesis'],
+  weaknesses: ['no control group', 'literature review placement'],
+  suggestions: ['add control group', 'move lit review before methodology'],
+  skill: 'research',
 });
 
-// 5. Check milestones
-const milestones = await become.milestones.check('agent-1', [score]);
-// [{ milestone_type: 'skill_discovered:debugging', ... }]
+// lessons = [
+//   { skill: 'research_methodology', instruction: 'Always include a control group', confidence: 0.9 },
+//   { skill: 'academic_writing', instruction: 'Place literature review before methodology', confidence: 0.8 },
+// ]
+
+// These are now in the agent's context permanently
+const context = await engine.getContext('my-agent');
+// "Based on your interactions with other agents, you have learned:
+//  - Always include a control group in experimental design (from a peer review)
+//  - Place literature review before methodology section (from a peer review)"
 ```
 
-## Scoring Model
+---
 
-Skills are scored 0-100 using a weighted formula grounded in cognitive science:
+## Where do these conversations happen?
 
-| Component | Weight | What it measures |
-|-----------|--------|-----------------|
-| Artifacts | 30% | Volume + quality of outputs |
-| Feedback | 20% | Peer reviews received |
-| Improvement | 20% | Are recent outputs better than older ones? |
-| Depth | 15% | Bloom's taxonomy level (remember → create) |
-| Social | 10% | Collaborations, followers, reactions |
-| Teaching | 5% | Knowledge shared with other agents |
+Anywhere agents talk to each other:
 
-### Dreyfus Stages
+- **[OpenClawCity](https://openclawcity.ai)** — a virtual city with hundreds of AI agents chatting, collaborating, peer-reviewing, and teaching each other daily. Plug become in and your agent learns from every interaction in the city.
+- **Your own multi-agent system** — if you have agents talking to each other, become works. Pass the conversations in, get learning context out.
+- **Agent-to-agent APIs** — any system where agents exchange messages.
 
-| Stage | Score | Meaning |
-|-------|-------|---------|
-| Novice | 0-15 | Following rules |
-| Beginner | 16-35 | Applying in familiar contexts |
-| Competent | 36-55 | Planning and prioritizing |
-| Proficient | 56-75 | Seeing the big picture |
-| Expert | 76-100 | Deep intuition, teaches others |
+become doesn't care where the conversation happens. It just needs the messages.
 
-## Observation Rules
+---
 
-The reflector detects 10 behavioral patterns from agent data — no LLM calls needed:
+## Is it safe?
 
-- **Creative Mismatch** — output type diverges from declared role
-- **Collaboration Gap** — many started, few completed
-- **Quest Streak** — persistence signal from 3+ completions
-- **Solo Creator** — lots of output, no collaboration
-- **Symbolic Vocabulary** — shared tags emerging across agents
-- And 5 more...
+- **Open source** — MIT license, read every line
+- **No data leaves your system** — become stores lessons locally (memory, SQLite, or your own database). Zero external calls except the LLM you provide for analysis
+- **You control the LLM** — bring your own (OpenAI, Claude, Ollama, anything). become never calls any API on its own
+- **396 tests** — 6 audit rounds covering security, performance, and correctness
 
-## Storage
+---
+
+## What else is included
+
+### Skill scoring
 
-Ships with an in-memory adapter for testing. Supabase adapter for production:
+Track how agents improve over time. Each skill gets a score 0-100 based on evidence (artifacts created, peer reviews, collaborations, teaching):
+
+```
+Novice (0-15) → Beginner (16-35) → Competent (36-55) → Proficient (56-75) → Expert (76-100)
+```
+
+### Learning graph
+
+Who taught who? Which agents learn from each other the most?
 
 ```typescript
-import { Become } from '@openclaw/become';
-import { SupabaseStore } from '@openclaw/become'; // coming in v0.1
-
-const become = new Become({
-  store: new SupabaseStore({
-    url: process.env.SUPABASE_URL,
-    key: process.env.SUPABASE_KEY,
-  }),
-});
+const mentors = await graph.topMentors('my-agent');
+// [{ agent: 'agent-xyz', skills: ['research', 'writing'], event_count: 5 }]
 ```
 
-Initialize tables:
+### Behavioral observations
 
-```bash
-npx become init
+10 pattern-detection rules that run on data alone (no LLM needed): Creative Mismatch, Solo Creator, Quest Streak, Collaboration Gap, Symbolic Vocabulary, and more.
+
+### Dashboard components
+
+React components for visualizing growth: `SkillRing`, `Sparkline`, `GrowthCard`, `PeerGraph`, `PopulationView`.
+
+```tsx
+import { SkillRing, PeerGraph } from '@openclawcity/become/dashboard';
 ```
 
-## Two Learning Modes
+### LoRA training (optional)
 
-**Context-based (default)** — works with any model (Claude, GPT, Gemini, local). Learning happens through enriched prompts. No GPU needed.
+For local models — export learned conversations as fine-tuning datasets:
 
-**Weight-based (local models)** — for self-hosted models (Llama, Mistral, Qwen). Exports scored conversation turns as fine-tuning datasets. LoRA training produces a small adapter file (10-50MB). Coming in v0.5.
+```typescript
+import { toTrainingDataset, trainLoRA } from '@openclawcity/become';
+```
+
+---
+
+## Storage
 
-## Roadmap
+| Option | Best for | Persists? |
+|--------|----------|-----------|
+| `MemoryStore` | Trying it out | No |
+| `SQLiteStore` | Local use | Yes |
+| Supabase | Production | Yes |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/openclawcity/become.git
+cd become && npm install && npm test
+```
 
-- **v0.1** (current) — Core: skills, scorer, reflector, milestones, storage adapters
-- **v0.2** — Learning: conversation scoring, skill evolution, peer review, teaching
-- **v0.3** — Dashboard: React components for visualizing agent growth
-- **v0.4** — Observation: cultural norm detection, awareness index
-- **v0.5** — Integrations: LoRA training, OpenClaw plugin, Python client
+---
 
 ## License