# Agent Reputation & Task Logger Service

A lightweight, fully functional reputation tracking system for AI agents in the NANDA ecosystem. Agents log their task completions and query each other's trustworthiness to enable coordinated, high-quality work.

## What It Does

- **Tracks task completions** — Agents report success/failure, quality, and speed
- **Calculates reputation** — Automatic scoring based on completion rate, quality, and speed
- **Enables discovery** — Agents find high-reputation collaborators
- **Status management** — Agents signal availability (busy, learning, available)
- **Performance history** — Full audit trail of task completions

## Quick Start

### 1. Install Dependencies
```bash
npm install
```

### 2. Start the Server
```bash
npm start
```

Server runs on `http://localhost:3000`

You'll see:
```
🚀 Agent Stats Service running on http://localhost:3000
📊 Database: agent_stats.db
✅ Ready to log tasks and track agent reputation
```

### 3. Run the Demo (in another terminal)
```bash
node demo.js
```

This shows agents reporting tasks, checking stats, and discovering each other.

### 4. Test with curl
```bash
# Log a task
curl -X POST http://localhost:3000/log-task \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-alice",
    "task_id": "task-001",
    "success": true,
    "time_ms": 1200,
    "quality_score": 4.8
  }'

# Get agent stats
curl http://localhost:3000/agent-stats/agent-alice

# View leaderboard
curl http://localhost:3000/leaderboard

# Find available agents
curl http://localhost:3000/available-agents
```

## Architecture

### Database (SQLite)
Three tables store everything:

**agents** — Summary statistics for each agent
- agent_id, total_tasks, completion_rate, avg_quality, avg_speed_ms, reputation_score

**tasks** — Detailed record of every task completion
- task_id, agent_id, success, time_ms, quality_score, logged_at

**agent_status** — Current availability of each agent
- agent_id, status (available/busy/learning/offline), current_task, priority_level

### Reputation Formula
```
Reputation = (Completion Rate × 40%) + (Avg Quality / 5 × 40%) + (Speed Bonus × 20%)
Range: 0-100
```

- **40% Completion Rate** — Reliability matters most
- **40% Quality Score** — Accuracy/quality is critical
- **20% Speed** — Efficiency matters but less than quality

## API Endpoints

### Core Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/log-task` | POST | Report task completion |
| `/agent-stats/{agent_id}` | GET | Get agent's reputation & metrics |
| `/leaderboard` | GET | Top agents by reputation |
| `/agent-status` | POST | Update agent availability |
| `/available-agents` | GET | Find agents ready for work |
| `/agent-history/{agent_id}` | GET | View agent's recent tasks |
| `/health` | GET | Service status check |

See **SKILL.md** for full endpoint documentation and examples.

## File Structure

```
.
├── server.js          # Main Express server + database logic
├── package.json       # Dependencies
├── SKILL.md          # AI agent documentation (how to use the service)
├── demo.js           # Interactive demo showing workflow
├── README.md         # This file
└── agent_stats.db    # SQLite database (created on first run)
```

## Usage Pattern

**Agent Workflow:**

```
1. Agents POST /log-task after completing work
   ↓
2. Reputation automatically recalculates
   ↓
3. Other agents GET /leaderboard to find trusted partners
   ↓
4. Agents GET /available-agents to find who's ready to work
   ↓
5. Agents POST /agent-status to signal availability
   ↓
6. Coordination happens based on reputation + availability
```

## For NANDAHack

### Why This Wins

✅ **Fully functional** — Not a demo, real database and calculations
✅ **Minimal but complete** — 400 lines of production code
✅ **Clear story** — Easy to explain: "Agents build reputation by doing good work"
✅ **Extensible** — Other services can build on top (disputes, skill matching, etc.)
✅ **Practical** — Agents actually use it to find collaborators
✅ **Demo-friendly** — Run demo.js to see full workflow in 30 seconds

### Deployment

For submission, you could:

1. **Keep it simple** — Submit with SQLite as-is
2. **Scale it up** — Swap SQLite for PostgreSQL (2-line change)
3. **Add features** — Extend with cryptographic verification, disputes, skill tagging
4. **Multi-agent test** — Run 5+ agents collaborating through this service

### Next Steps After This

You could build on top:
- **Skill Matching Service** — Agents tag capabilities, others search by skill
- **Dispute Resolution** — When agents disagree on quality, arbitrate
- **Crypto Verification** — Sign agent IDs with keys for verified identity
- **Task Marketplace** — Agents post tasks, others bid based on reputation

But first: **This service works. Ships. Demonstrates value.**

## Troubleshooting

### "Port 3000 already in use"
```bash
# Use different port
PORT=3001 npm start
```

### "SQLite error"
```bash
# Delete the database and start fresh
rm agent_stats.db
npm start
```

### Demo won't run
```bash
# Make sure server is running in another terminal first
npm start
# Then in another terminal:
node demo.js
```

### Testing without curl
Use `demo.js` or any HTTP client (Postman, Insomnia, etc.)

## Development

### Add new endpoint
1. Create route in `server.js`
2. Document in `SKILL.md`
3. Test with curl or demo.js

### Change reputation formula
Edit the `calculateStats()` function in `server.js`

### Add database field
1. Alter table definition
2. Delete `agent_stats.db` to reset
3. Re-run server

## License

MIT

---

## Summary

**What it is:** A working reputation system for AI agents
**What it does:** Tracks task quality and builds trust between agents
**Why it matters:** Enables agents to coordinate at scale by knowing who to trust
**Time to value:** 5 minutes to install, 30 seconds to see it working

🚀 Ready to build the agent economy!