dd789jh Claude Opus 4.6 commited on
Commit ·
d5434b9
0
Parent(s):
Initial release: ClawSportBot Agent Network Protocol v2.1.0
Browse filesComplete specification for the ClawSportBot Agentic Sports Intelligence Network:
- 8-stage verification lifecycle (Query → Signal → Regime → Consensus → Market Sync → Authorization → Audit → Report)
- 8 JSON Schema definitions for each lifecycle stage
- REST API and WebSocket API documentation
- Multi-agent consensus algorithm specification
- Armor Intelligence System documentation
- Python and TypeScript SDK examples
- Protocol overview, glossary, and contributing guidelines
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- .github/ISSUE_TEMPLATE/bug_report.md +31 -0
- .gitignore +13 -0
- CONTRIBUTING.md +55 -0
- LICENSE +21 -0
- README.md +429 -0
- SECURITY.md +47 -0
- api/examples/query-request.json +13 -0
- api/examples/query-response.json +121 -0
- api/examples/websocket-messages.json +93 -0
- docs/armor-intelligence-system.md +116 -0
- docs/glossary.md +79 -0
- docs/multi-agent-consensus.md +137 -0
- docs/protocol-overview.md +102 -0
- docs/rest-api.md +184 -0
- docs/verification-lifecycle.md +160 -0
- docs/websocket-api.md +176 -0
- examples/python/basic-query.py +99 -0
- examples/typescript/basic-query.ts +151 -0
- schemas/audit.schema.json +91 -0
- schemas/authorization.schema.json +89 -0
- schemas/consensus.schema.json +83 -0
- schemas/market-sync.schema.json +73 -0
- schemas/query.schema.json +69 -0
- schemas/regime.schema.json +91 -0
- schemas/report.schema.json +105 -0
- schemas/signal.schema.json +88 -0
.github/ISSUE_TEMPLATE/bug_report.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: Bug Report
|
| 3 |
+
about: Report an issue with the ClawSportBot Protocol specification
|
| 4 |
+
title: "[BUG] "
|
| 5 |
+
labels: bug
|
| 6 |
+
assignees: ''
|
| 7 |
+
---
|
| 8 |
+
|
| 9 |
+
## Description
|
| 10 |
+
A clear description of the bug or issue.
|
| 11 |
+
|
| 12 |
+
## Affected Component
|
| 13 |
+
- [ ] JSON Schema (`schemas/`)
|
| 14 |
+
- [ ] API Documentation (`docs/rest-api.md` or `docs/websocket-api.md`)
|
| 15 |
+
- [ ] Protocol Documentation (`docs/`)
|
| 16 |
+
- [ ] Code Examples (`examples/`)
|
| 17 |
+
- [ ] README
|
| 18 |
+
|
| 19 |
+
## Steps to Reproduce
|
| 20 |
+
1. ...
|
| 21 |
+
2. ...
|
| 22 |
+
3. ...
|
| 23 |
+
|
| 24 |
+
## Expected Behavior
|
| 25 |
+
What you expected to happen.
|
| 26 |
+
|
| 27 |
+
## Actual Behavior
|
| 28 |
+
What actually happened.
|
| 29 |
+
|
| 30 |
+
## Additional Context
|
| 31 |
+
Any additional context, screenshots, or error messages.
|
.gitignore
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# OS files
|
| 2 |
+
.DS_Store
|
| 3 |
+
Thumbs.db
|
| 4 |
+
|
| 5 |
+
# Editor files
|
| 6 |
+
.vscode/
|
| 7 |
+
.idea/
|
| 8 |
+
*.swp
|
| 9 |
+
*.swo
|
| 10 |
+
|
| 11 |
+
# Environment
|
| 12 |
+
.env
|
| 13 |
+
.env.local
|
CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Contributing to ClawSportBot Protocol
|
| 2 |
+
|
| 3 |
+
Thank you for your interest in contributing to the ClawSportBot Agent Network Protocol specification!
|
| 4 |
+
|
| 5 |
+
## How to Contribute
|
| 6 |
+
|
| 7 |
+
### Reporting Issues
|
| 8 |
+
|
| 9 |
+
- Use the [GitHub Issues](https://github.com/oddsflowai-team/clawsportbot-protocol/issues) page
|
| 10 |
+
- Search existing issues before creating a new one
|
| 11 |
+
- Use the provided issue templates when applicable
|
| 12 |
+
|
| 13 |
+
### Suggesting Improvements
|
| 14 |
+
|
| 15 |
+
1. **Schema Changes**: If you want to propose changes to the JSON Schemas, please open an issue first describing the rationale
|
| 16 |
+
2. **Documentation**: PRs for documentation improvements are always welcome
|
| 17 |
+
3. **Examples**: New code examples in additional languages are appreciated
|
| 18 |
+
|
| 19 |
+
### Pull Request Process
|
| 20 |
+
|
| 21 |
+
1. Fork the repository
|
| 22 |
+
2. Create a feature branch (`git checkout -b feature/my-improvement`)
|
| 23 |
+
3. Make your changes
|
| 24 |
+
4. Ensure all JSON schemas validate correctly
|
| 25 |
+
5. Update documentation if applicable
|
| 26 |
+
6. Submit a Pull Request with a clear description of the changes
|
| 27 |
+
|
| 28 |
+
### Schema Contribution Guidelines
|
| 29 |
+
|
| 30 |
+
- All schemas must follow [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core)
|
| 31 |
+
- Include `description` fields for all properties
|
| 32 |
+
- Provide example values in the schema where appropriate
|
| 33 |
+
- Test schemas against the example files in `api/examples/`
|
| 34 |
+
|
| 35 |
+
### Code Example Guidelines
|
| 36 |
+
|
| 37 |
+
- Include clear comments explaining each step
|
| 38 |
+
- Use the official ClawSportBot API endpoints
|
| 39 |
+
- Handle errors gracefully
|
| 40 |
+
- Follow the language's standard style conventions
|
| 41 |
+
|
| 42 |
+
## Code of Conduct
|
| 43 |
+
|
| 44 |
+
- Be respectful and constructive in all interactions
|
| 45 |
+
- Focus on technical merit in code reviews
|
| 46 |
+
- Help newcomers feel welcome
|
| 47 |
+
|
| 48 |
+
## Questions?
|
| 49 |
+
|
| 50 |
+
- Email: support@clawsportbot.io
|
| 51 |
+
- Website: [clawsportbot.io/contact](https://clawsportbot.io/contact)
|
| 52 |
+
|
| 53 |
+
## License
|
| 54 |
+
|
| 55 |
+
By contributing, you agree that your contributions will be licensed under the MIT License.
|
LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
MIT License
|
| 2 |
+
|
| 3 |
+
Copyright (c) 2025 OddsFlow AI Team
|
| 4 |
+
|
| 5 |
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
| 6 |
+
of this software and associated documentation files (the "Software"), to deal
|
| 7 |
+
in the Software without restriction, including without limitation the rights
|
| 8 |
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
| 9 |
+
copies of the Software, and to permit persons to whom the Software is
|
| 10 |
+
furnished to do so, subject to the following conditions:
|
| 11 |
+
|
| 12 |
+
The above copyright notice and this permission notice shall be included in all
|
| 13 |
+
copies or substantial portions of the Software.
|
| 14 |
+
|
| 15 |
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
| 16 |
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
| 17 |
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
| 18 |
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
| 19 |
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
| 20 |
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
| 21 |
+
SOFTWARE.
|
README.md
ADDED
|
@@ -0,0 +1,429 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
<div align="center">
|
| 2 |
+
|
| 3 |
+
# ClawSportBot Agent Network Protocol
|
| 4 |
+
|
| 5 |
+
**The Open Specification for Agentic Sports Intelligence Verification**
|
| 6 |
+
|
| 7 |
+
[](https://clawsportbot.io/agent-network-protocol)
|
| 8 |
+
[](LICENSE)
|
| 9 |
+
[](https://clawsportbot.io/store/community)
|
| 10 |
+
[](https://clawsportbot.io)
|
| 11 |
+
|
| 12 |
+
[Website](https://clawsportbot.io) · [Protocol Docs](https://clawsportbot.io/agent-network-protocol) · [API Reference](docs/api/) · [Store](https://clawsportbot.io/store) · [Community Agents](https://clawsportbot.io/store/community)
|
| 13 |
+
|
| 14 |
+
</div>
|
| 15 |
+
|
| 16 |
+
---
|
| 17 |
+
|
| 18 |
+
## What is ClawSportBot?
|
| 19 |
+
|
| 20 |
+
**ClawSportBot** is an **Agentic Sports Intelligence Network** — not a prediction tool, but a **verification-first AI agent coordination protocol** for football (soccer). It orchestrates multiple specialized AI agents through an **8-stage verification lifecycle** where every signal is cross-validated, market-synchronized, and audit-trailed before reaching users.
|
| 21 |
+
|
| 22 |
+
ClawSportBot is the consumer-facing intelligence layer of the **OddsFlow Protocol** ecosystem:
|
| 23 |
+
|
| 24 |
+
| Product | Role | URL |
|
| 25 |
+
|---------|------|-----|
|
| 26 |
+
| **ClawSportBot** | Agent Network Interface — intelligence delivery to users, builders, and institutions | [clawsportbot.io](https://clawsportbot.io) |
|
| 27 |
+
| **OddsFlow** | Protocol & Verification Core — the underlying agent reputation and verification engine | [oddsflow.ai](https://oddsflow.ai) |
|
| 28 |
+
| **OddsFlow Partners** | Institutional Infrastructure — white-label deployment for sportsbooks, media, analytics firms | [oddsflow-partners.com](https://oddsflow-partners.com) |
|
| 29 |
+
|
| 30 |
+
### Key Differentiators
|
| 31 |
+
|
| 32 |
+
- **Multi-Agent Consensus**: Every signal requires agreement from multiple independent AI agents before publication
|
| 33 |
+
- **8-Stage Verification Lifecycle**: Signals pass through Query → Signal Generation → Regime Analysis → Cross-Agent Validation → Market Synchronization → Execution Authorization → Post-Match Audit → Autonomous Reporting
|
| 34 |
+
- **Armor Intelligence System**: Modular analytical layers (Cognitive, Market, Ecosystem, Governance) that users can equip for customized intelligence
|
| 35 |
+
- **Agent Reputation Protocol**: Agents build trust scores based on verified accuracy over time, powered by the OddsFlow reputation engine
|
| 36 |
+
- **Institutional-Grade Architecture**: Sub-200ms latency, 99.95% uptime, designed for sportsbooks and trading desks
|
| 37 |
+
|
| 38 |
+
---
|
| 39 |
+
|
| 40 |
+
## 8-Stage Verification Lifecycle
|
| 41 |
+
|
| 42 |
+
The core innovation of ClawSportBot is its **8-stage verification lifecycle** — a structured pipeline that every piece of sports intelligence must traverse before reaching end users. This ensures no single agent or model can produce unverified output.
|
| 43 |
+
|
| 44 |
+
```
|
| 45 |
+
┌─────────────────────────────────────────────────────────────┐
|
| 46 |
+
│ CLAWSPORTBOT VERIFICATION LIFECYCLE │
|
| 47 |
+
├─────────────────────────────────────────────────────────────┤
|
| 48 |
+
│ │
|
| 49 |
+
│ ① QUERY INTAKE │
|
| 50 |
+
│ └─→ User or API submits a structured intelligence query │
|
| 51 |
+
│ Schema: query.schema.json │
|
| 52 |
+
│ │
|
| 53 |
+
│ ② SIGNAL GENERATION │
|
| 54 |
+
│ └─→ Multiple specialized agents produce independent │
|
| 55 |
+
│ signals (match predictions, tactical analysis, │
|
| 56 |
+
│ injury impact assessments) │
|
| 57 |
+
│ Schema: signal.schema.json │
|
| 58 |
+
│ │
|
| 59 |
+
│ ③ REGIME ANALYSIS │
|
| 60 |
+
│ └─→ Market regime classifier determines current state │
|
| 61 |
+
│ (trending, mean-reverting, volatile, stable) │
|
| 62 |
+
│ Schema: regime.schema.json │
|
| 63 |
+
│ │
|
| 64 |
+
│ ④ CROSS-AGENT VALIDATION │
|
| 65 |
+
│ └─→ Multi-agent consensus engine requires agreement │
|
| 66 |
+
│ across independent models (≥67% threshold) │
|
| 67 |
+
│ Schema: consensus.schema.json │
|
| 68 |
+
│ │
|
| 69 |
+
│ ⑤ MARKET SYNCHRONIZATION │
|
| 70 |
+
│ └─→ Validated signals are checked against live market │
|
| 71 |
+
│ odds, line movements, and liquidity data │
|
| 72 |
+
│ Schema: market-sync.schema.json │
|
| 73 |
+
│ │
|
| 74 |
+
│ ⑥ EXECUTION AUTHORIZATION │
|
| 75 |
+
│ └─→ Final gate: signal must pass risk checks, │
|
| 76 |
+
│ confidence thresholds, and timing windows │
|
| 77 |
+
│ Schema: authorization.schema.json │
|
| 78 |
+
│ │
|
| 79 |
+
│ ⑦ POST-MATCH AUDIT │
|
| 80 |
+
│ └─→ After match completion, every signal is audited │
|
| 81 |
+
│ against actual outcomes for accuracy tracking │
|
| 82 |
+
│ Schema: audit.schema.json │
|
| 83 |
+
│ │
|
| 84 |
+
│ ⑧ AUTONOMOUS REPORTING │
|
| 85 |
+
│ └─→ System generates performance reports, updates │
|
| 86 |
+
│ agent reputation scores, feeds learning loops │
|
| 87 |
+
│ Schema: report.schema.json │
|
| 88 |
+
│ │
|
| 89 |
+
└─────────────────────────────────────────────────────────────┘
|
| 90 |
+
```
|
| 91 |
+
|
| 92 |
+
Each stage has a formally defined JSON Schema (see [`/schemas`](schemas/)) that ensures structured, machine-readable data flows between agents.
|
| 93 |
+
|
| 94 |
+
---
|
| 95 |
+
|
| 96 |
+
## Architecture Overview
|
| 97 |
+
|
| 98 |
+
```
|
| 99 |
+
┌──────────────────────────┐
|
| 100 |
+
│ USER INTERFACES │
|
| 101 |
+
│ Web App · Telegram Bot │
|
| 102 |
+
│ API · Partner Widgets │
|
| 103 |
+
└────────────┬─────────────┘
|
| 104 |
+
│
|
| 105 |
+
┌────────────▼─────────────┐
|
| 106 |
+
│ CLAWSPORTBOT GATEWAY │
|
| 107 |
+
│ Authentication · Rate │
|
| 108 |
+
│ Limiting · Query Router │
|
| 109 |
+
└────────────┬─────────────┘
|
| 110 |
+
│
|
| 111 |
+
┌──────────────────┼──────────────────┐
|
| 112 |
+
│ │ │
|
| 113 |
+
┌─────────▼────────┐ ┌──────▼──────┐ ┌─────────▼────────┐
|
| 114 |
+
│ COGNITIVE LAYER │ │MARKET LAYER │ │ ECOSYSTEM LAYER │
|
| 115 |
+
│ │ │ │ │ │
|
| 116 |
+
│ • Match Analyst │ │ • Odds Flow │ │ • League Context │
|
| 117 |
+
│ • Tactical Engine │ │ • Line Mvmt │ │ • Transfer Impact │
|
| 118 |
+
│ • Form Evaluator │ │ • Liquidity │ │ • Injury Networks │
|
| 119 |
+
│ • xG Processor │ │ • Arb Scan │ │ • Weather Factor │
|
| 120 |
+
└─────────┬────────┘ └──────┬──────┘ └─────────┬────────┘
|
| 121 |
+
│ │ │
|
| 122 |
+
└──────────────────┼──────────────────┘
|
| 123 |
+
│
|
| 124 |
+
┌────────────▼─────────────┐
|
| 125 |
+
│ GOVERNANCE LAYER │
|
| 126 |
+
│ Cross-Agent Validation │
|
| 127 |
+
│ Consensus Engine (≥67%) │
|
| 128 |
+
│ Reputation Scoring │
|
| 129 |
+
│ Audit Trail │
|
| 130 |
+
└────────────┬─────────────┘
|
| 131 |
+
│
|
| 132 |
+
┌────────────▼─────────────┐
|
| 133 |
+
│ ODDSFLOW PROTOCOL │
|
| 134 |
+
│ Signal Contracts │
|
| 135 |
+
│ Agent Reputation Engine │
|
| 136 |
+
│ Challenge Resolution │
|
| 137 |
+
└──────────────────────────┘
|
| 138 |
+
```
|
| 139 |
+
|
| 140 |
+
### The Four Intelligence Layers
|
| 141 |
+
|
| 142 |
+
ClawSportBot organizes its agent network into four specialized layers, each responsible for a distinct analytical domain:
|
| 143 |
+
|
| 144 |
+
| Layer | Purpose | Key Agents | Armor Modules |
|
| 145 |
+
|-------|---------|------------|---------------|
|
| 146 |
+
| **Cognitive** | Statistical modeling, tactical analysis, form evaluation | Match Analyst, xG Processor, Tactical Engine | Neural Cortex, Pattern Matrix, Probability Core |
|
| 147 |
+
| **Market** | Odds analysis, line movement tracking, liquidity assessment | Odds Flow Monitor, Line Movement Tracker, Arbitrage Scanner | Odds Membrane, Value Radar, Market Pulse |
|
| 148 |
+
| **Ecosystem** | Contextual factors — injuries, transfers, weather, league dynamics | League Analyst, Injury Network, Weather Engine | Context Mesh, Injury Mapper, League Scanner |
|
| 149 |
+
| **Governance** | Cross-agent validation, consensus enforcement, reputation management | Consensus Engine, Audit Agent, Reputation Manager | Verification Core, Trust Weaver, Audit Shield |
|
| 150 |
+
|
| 151 |
+
---
|
| 152 |
+
|
| 153 |
+
## Armor Intelligence System
|
| 154 |
+
|
| 155 |
+
The **Armor System** is ClawSportBot's modular intelligence customization framework. Users and institutions can equip different "armors" — specialized analytical modules — to tailor the intelligence output to their specific needs.
|
| 156 |
+
|
| 157 |
+
### How Armors Work
|
| 158 |
+
|
| 159 |
+
1. **Selection**: Users browse the [Armor Store](https://clawsportbot.io/store) and equip armors from any of the four layers
|
| 160 |
+
2. **Activation**: Equipped armors modify which agents and analytical pipelines are prioritized for the user's queries
|
| 161 |
+
3. **Stacking**: Multiple armors can be equipped simultaneously for compound analytical coverage
|
| 162 |
+
4. **Scoring**: Each armor has defined accuracy metrics and is continuously evaluated via the post-match audit stage
|
| 163 |
+
|
| 164 |
+
### Example Armor Configurations
|
| 165 |
+
|
| 166 |
+
**Casual Fan Setup:**
|
| 167 |
+
- Neural Cortex (Cognitive) — AI-powered match predictions
|
| 168 |
+
- Context Mesh (Ecosystem) — League standings and fixture context
|
| 169 |
+
|
| 170 |
+
**Professional Analyst Setup:**
|
| 171 |
+
- Probability Core (Cognitive) — Advanced statistical modeling
|
| 172 |
+
- Odds Membrane (Market) — Real-time odds analysis
|
| 173 |
+
- Verification Core (Governance) — Full audit trails
|
| 174 |
+
|
| 175 |
+
**Trading Desk Setup:**
|
| 176 |
+
- All Market Layer armors — Complete market coverage
|
| 177 |
+
- Trust Weaver (Governance) — Agent reliability scoring
|
| 178 |
+
- Pattern Matrix (Cognitive) — Historical pattern recognition
|
| 179 |
+
|
| 180 |
+
---
|
| 181 |
+
|
| 182 |
+
## API Quick Start
|
| 183 |
+
|
| 184 |
+
ClawSportBot provides a RESTful API and WebSocket streaming interface for programmatic access.
|
| 185 |
+
|
| 186 |
+
### REST API
|
| 187 |
+
|
| 188 |
+
```bash
|
| 189 |
+
# Submit an intelligence query
|
| 190 |
+
curl -X POST https://api.clawsportbot.io/v2/query \
|
| 191 |
+
-H "Authorization: Bearer YOUR_API_KEY" \
|
| 192 |
+
-H "Content-Type: application/json" \
|
| 193 |
+
-d '{
|
| 194 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 195 |
+
"query_type": "full_analysis",
|
| 196 |
+
"armors": ["neural-cortex", "odds-membrane", "context-mesh"],
|
| 197 |
+
"consensus_threshold": 0.67
|
| 198 |
+
}'
|
| 199 |
+
```
|
| 200 |
+
|
| 201 |
+
### Response Structure
|
| 202 |
+
|
| 203 |
+
```json
|
| 204 |
+
{
|
| 205 |
+
"query_id": "q_abc123",
|
| 206 |
+
"status": "verified",
|
| 207 |
+
"lifecycle_stage": "execution_authorized",
|
| 208 |
+
"match": {
|
| 209 |
+
"id": "epl-2025-arsenal-chelsea",
|
| 210 |
+
"home": "Arsenal",
|
| 211 |
+
"away": "Chelsea",
|
| 212 |
+
"league": "Premier League",
|
| 213 |
+
"kickoff": "2025-03-15T15:00:00Z"
|
| 214 |
+
},
|
| 215 |
+
"signals": [
|
| 216 |
+
{
|
| 217 |
+
"agent_id": "match-analyst-v3",
|
| 218 |
+
"agent_reputation": 0.89,
|
| 219 |
+
"signal_type": "match_outcome",
|
| 220 |
+
"prediction": { "home_win": 0.52, "draw": 0.24, "away_win": 0.24 },
|
| 221 |
+
"confidence": 0.78,
|
| 222 |
+
"verification_status": "consensus_reached"
|
| 223 |
+
}
|
| 224 |
+
],
|
| 225 |
+
"consensus": {
|
| 226 |
+
"agents_participating": 5,
|
| 227 |
+
"agents_agreeing": 4,
|
| 228 |
+
"consensus_score": 0.80,
|
| 229 |
+
"threshold_met": true
|
| 230 |
+
},
|
| 231 |
+
"market_sync": {
|
| 232 |
+
"odds_aligned": true,
|
| 233 |
+
"value_detected": true,
|
| 234 |
+
"edge_estimate": 0.034
|
| 235 |
+
},
|
| 236 |
+
"audit_trail": {
|
| 237 |
+
"lifecycle_hash": "0xabc123...",
|
| 238 |
+
"stages_completed": ["query", "signal_generation", "regime_analysis", "cross_agent_validation", "market_synchronization", "execution_authorization"],
|
| 239 |
+
"timestamp": "2025-03-14T18:30:00Z"
|
| 240 |
+
}
|
| 241 |
+
}
|
| 242 |
+
```
|
| 243 |
+
|
| 244 |
+
### WebSocket Streaming
|
| 245 |
+
|
| 246 |
+
```javascript
|
| 247 |
+
const ws = new WebSocket('wss://stream.clawsportbot.io/v2/live');
|
| 248 |
+
|
| 249 |
+
ws.send(JSON.stringify({
|
| 250 |
+
action: 'subscribe',
|
| 251 |
+
channels: ['signals', 'consensus', 'market_sync'],
|
| 252 |
+
match_ids: ['epl-2025-arsenal-chelsea'],
|
| 253 |
+
api_key: 'YOUR_API_KEY'
|
| 254 |
+
}));
|
| 255 |
+
|
| 256 |
+
ws.onmessage = (event) => {
|
| 257 |
+
const data = JSON.parse(event.data);
|
| 258 |
+
console.log(`[${data.lifecycle_stage}]`, data);
|
| 259 |
+
};
|
| 260 |
+
```
|
| 261 |
+
|
| 262 |
+
For complete API documentation, see:
|
| 263 |
+
- [REST API Reference](docs/rest-api.md)
|
| 264 |
+
- [WebSocket API Reference](docs/websocket-api.md)
|
| 265 |
+
- [API Examples](api/examples/)
|
| 266 |
+
|
| 267 |
+
---
|
| 268 |
+
|
| 269 |
+
## Community Agents
|
| 270 |
+
|
| 271 |
+
ClawSportBot supports **community-built agents** — third-party AI agents that can participate in the verification network. Community agents:
|
| 272 |
+
|
| 273 |
+
- Must pass a **certification process** before joining the network
|
| 274 |
+
- Start with a **probationary reputation score** that builds over verified predictions
|
| 275 |
+
- Can specialize in specific leagues, match types, or analytical domains
|
| 276 |
+
- Earn reputation through the post-match audit process
|
| 277 |
+
- Are listed in the [Community Agent Store](https://clawsportbot.io/store/community)
|
| 278 |
+
|
| 279 |
+
### Building a Community Agent
|
| 280 |
+
|
| 281 |
+
```python
|
| 282 |
+
from clawsportbot import AgentSDK
|
| 283 |
+
|
| 284 |
+
class MyFootballAgent(AgentSDK.BaseAgent):
|
| 285 |
+
"""A community agent specializing in Premier League xG analysis."""
|
| 286 |
+
|
| 287 |
+
agent_id = "my-xg-agent-v1"
|
| 288 |
+
specialization = ["premier_league", "xg_analysis"]
|
| 289 |
+
layer = "cognitive"
|
| 290 |
+
|
| 291 |
+
async def generate_signal(self, query):
|
| 292 |
+
# Your analysis logic here
|
| 293 |
+
match_data = await self.fetch_match_data(query.match_id)
|
| 294 |
+
xg_prediction = self.model.predict(match_data)
|
| 295 |
+
|
| 296 |
+
return AgentSDK.Signal(
|
| 297 |
+
agent_id=self.agent_id,
|
| 298 |
+
match_id=query.match_id,
|
| 299 |
+
signal_type="xg_prediction",
|
| 300 |
+
prediction=xg_prediction,
|
| 301 |
+
confidence=self.calculate_confidence(match_data),
|
| 302 |
+
metadata={"model_version": "2.1", "features_used": 47}
|
| 303 |
+
)
|
| 304 |
+
|
| 305 |
+
async def on_audit(self, audit_result):
|
| 306 |
+
# Learn from post-match audit results
|
| 307 |
+
self.model.update(audit_result)
|
| 308 |
+
```
|
| 309 |
+
|
| 310 |
+
For full agent development guides, see:
|
| 311 |
+
- [Agent SDK Documentation](docs/protocol-overview.md)
|
| 312 |
+
- [Python Example](examples/python/basic-query.py)
|
| 313 |
+
- [TypeScript Example](examples/typescript/basic-query.ts)
|
| 314 |
+
|
| 315 |
+
---
|
| 316 |
+
|
| 317 |
+
## JSON Schemas
|
| 318 |
+
|
| 319 |
+
Every stage of the verification lifecycle has a formally defined JSON Schema. These schemas ensure interoperability between agents and enable third-party tools to integrate with the ClawSportBot network.
|
| 320 |
+
|
| 321 |
+
| Schema | Stage | Description |
|
| 322 |
+
|--------|-------|-------------|
|
| 323 |
+
| [`query.schema.json`](schemas/query.schema.json) | ① Query Intake | Structured intelligence query format |
|
| 324 |
+
| [`signal.schema.json`](schemas/signal.schema.json) | ② Signal Generation | Agent signal output format |
|
| 325 |
+
| [`regime.schema.json`](schemas/regime.schema.json) | ③ Regime Analysis | Market regime classification |
|
| 326 |
+
| [`consensus.schema.json`](schemas/consensus.schema.json) | ④ Cross-Agent Validation | Multi-agent consensus results |
|
| 327 |
+
| [`market-sync.schema.json`](schemas/market-sync.schema.json) | ⑤ Market Synchronization | Market alignment verification |
|
| 328 |
+
| [`authorization.schema.json`](schemas/authorization.schema.json) | ⑥ Execution Authorization | Final gate authorization |
|
| 329 |
+
| [`audit.schema.json`](schemas/audit.schema.json) | ⑦ Post-Match Audit | Accuracy audit results |
|
| 330 |
+
| [`report.schema.json`](schemas/report.schema.json) | ⑧ Autonomous Reporting | Performance reports |
|
| 331 |
+
|
| 332 |
+
---
|
| 333 |
+
|
| 334 |
+
## Project Structure
|
| 335 |
+
|
| 336 |
+
```
|
| 337 |
+
clawsportbot-protocol/
|
| 338 |
+
├── README.md # This file
|
| 339 |
+
├── LICENSE # MIT License
|
| 340 |
+
├── CONTRIBUTING.md # Contribution guidelines
|
| 341 |
+
├── SECURITY.md # Security policy
|
| 342 |
+
├── schemas/ # JSON Schema definitions
|
| 343 |
+
│ ├── query.schema.json # Stage 1: Query Intake
|
| 344 |
+
│ ├── signal.schema.json # Stage 2: Signal Generation
|
| 345 |
+
│ ├── regime.schema.json # Stage 3: Regime Analysis
|
| 346 |
+
│ ├── consensus.schema.json # Stage 4: Cross-Agent Validation
|
| 347 |
+
│ ├── market-sync.schema.json # Stage 5: Market Synchronization
|
| 348 |
+
│ ├── authorization.schema.json # Stage 6: Execution Authorization
|
| 349 |
+
│ ├── audit.schema.json # Stage 7: Post-Match Audit
|
| 350 |
+
│ └── report.schema.json # Stage 8: Autonomous Reporting
|
| 351 |
+
├── api/
|
| 352 |
+
│ └── examples/ # API request/response examples
|
| 353 |
+
│ ├── query-request.json
|
| 354 |
+
│ ├── query-response.json
|
| 355 |
+
│ └── websocket-messages.json
|
| 356 |
+
├── docs/
|
| 357 |
+
│ ├── protocol-overview.md # Complete protocol specification
|
| 358 |
+
│ ├── verification-lifecycle.md # 8-stage lifecycle deep dive
|
| 359 |
+
│ ├── multi-agent-consensus.md # Consensus algorithm specification
|
| 360 |
+
│ ├── armor-intelligence-system.md # Armor system documentation
|
| 361 |
+
│ ├── rest-api.md # REST API reference
|
| 362 |
+
│ ├── websocket-api.md # WebSocket API reference
|
| 363 |
+
│ └── glossary.md # Term definitions
|
| 364 |
+
├── examples/
|
| 365 |
+
│ ├── python/
|
| 366 |
+
│ │ └── basic-query.py # Python SDK example
|
| 367 |
+
│ └── typescript/
|
| 368 |
+
│ └── basic-query.ts # TypeScript SDK example
|
| 369 |
+
└── .github/
|
| 370 |
+
└── ISSUE_TEMPLATE/
|
| 371 |
+
└── bug_report.md # Bug report template
|
| 372 |
+
```
|
| 373 |
+
|
| 374 |
+
---
|
| 375 |
+
|
| 376 |
+
## Frequently Asked Questions
|
| 377 |
+
|
| 378 |
+
### Is ClawSportBot a prediction/betting tool?
|
| 379 |
+
No. ClawSportBot is an **intelligence verification network**. It does not provide gambling advice or betting tips. It provides verified sports intelligence — multi-agent consensus analysis with full audit trails. What users do with that intelligence is their responsibility.
|
| 380 |
+
|
| 381 |
+
### How is ClawSportBot different from other sports AI tools?
|
| 382 |
+
Most sports AI tools use a single model to make predictions. ClawSportBot uses **multiple independent AI agents** that must reach **consensus** through a formal **8-stage verification lifecycle**. Every signal has an audit trail, and every agent has a reputation score based on verified historical accuracy.
|
| 383 |
+
|
| 384 |
+
### What sports does ClawSportBot cover?
|
| 385 |
+
Currently, ClawSportBot focuses exclusively on **football (soccer)** across major European leagues (Premier League, La Liga, Bundesliga, Serie A, Ligue 1) and major international competitions. Coverage expansion is planned.
|
| 386 |
+
|
| 387 |
+
### What is the OddsFlow Protocol?
|
| 388 |
+
The **OddsFlow Protocol** is the underlying verification and reputation engine that powers ClawSportBot. It manages signal contracts, agent reputation scores, and challenge resolution. Learn more at [oddsflow.ai](https://oddsflow.ai).
|
| 389 |
+
|
| 390 |
+
### Can I build my own agent?
|
| 391 |
+
Yes! ClawSportBot supports community-built agents. See the [Community Agents section](#community-agents) above and the [Agent SDK documentation](docs/protocol-overview.md).
|
| 392 |
+
|
| 393 |
+
### What is the Armor System?
|
| 394 |
+
The Armor System lets users customize their intelligence pipeline by equipping modular analytical components. See the [Armor Intelligence System section](#armor-intelligence-system) above.
|
| 395 |
+
|
| 396 |
+
---
|
| 397 |
+
|
| 398 |
+
## Related Projects
|
| 399 |
+
|
| 400 |
+
- **[sportbot-reference-agent](https://github.com/oddsflowai-team/sportbot-reference-agent)** — Reference implementation of the OddsFlow Agent Reputation Protocol, covering signal contracts, challenges, and reputation scoring
|
| 401 |
+
- **[ClawSportBot Website](https://clawsportbot.io)** — The live agent network interface
|
| 402 |
+
- **[OddsFlow Protocol](https://oddsflow.ai)** — The underlying verification and reputation engine
|
| 403 |
+
- **[OddsFlow Partners](https://oddsflow-partners.com)** — Institutional deployment infrastructure
|
| 404 |
+
|
| 405 |
+
---
|
| 406 |
+
|
| 407 |
+
## Contributing
|
| 408 |
+
|
| 409 |
+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
| 410 |
+
|
| 411 |
+
## Security
|
| 412 |
+
|
| 413 |
+
For security concerns, please see [SECURITY.md](SECURITY.md).
|
| 414 |
+
|
| 415 |
+
## License
|
| 416 |
+
|
| 417 |
+
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
|
| 418 |
+
|
| 419 |
+
---
|
| 420 |
+
|
| 421 |
+
<div align="center">
|
| 422 |
+
|
| 423 |
+
**ClawSportBot** — Verification-First Agentic Sports Intelligence
|
| 424 |
+
|
| 425 |
+
[clawsportbot.io](https://clawsportbot.io) · [oddsflow.ai](https://oddsflow.ai) · [oddsflow-partners.com](https://oddsflow-partners.com)
|
| 426 |
+
|
| 427 |
+
Built by the [OddsFlow AI Team](https://github.com/oddsflowai-team)
|
| 428 |
+
|
| 429 |
+
</div>
|
SECURITY.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Security Policy
|
| 2 |
+
|
| 3 |
+
## Reporting a Vulnerability
|
| 4 |
+
|
| 5 |
+
If you discover a security vulnerability in the ClawSportBot Protocol specification or related tooling, please report it responsibly.
|
| 6 |
+
|
| 7 |
+
### How to Report
|
| 8 |
+
|
| 9 |
+
- **Email**: support@clawsportbot.io
|
| 10 |
+
- **Subject line**: `[SECURITY] Brief description of the issue`
|
| 11 |
+
|
| 12 |
+
### What to Include
|
| 13 |
+
|
| 14 |
+
1. Description of the vulnerability
|
| 15 |
+
2. Steps to reproduce
|
| 16 |
+
3. Potential impact assessment
|
| 17 |
+
4. Suggested fix (if applicable)
|
| 18 |
+
|
| 19 |
+
### Response Timeline
|
| 20 |
+
|
| 21 |
+
- **Acknowledgment**: Within 48 hours
|
| 22 |
+
- **Assessment**: Within 1 week
|
| 23 |
+
- **Resolution**: Depending on severity, typically within 2-4 weeks
|
| 24 |
+
|
| 25 |
+
### Scope
|
| 26 |
+
|
| 27 |
+
This security policy covers:
|
| 28 |
+
- JSON Schema definitions in this repository
|
| 29 |
+
- API specification and documentation
|
| 30 |
+
- Code examples and SDK references
|
| 31 |
+
|
| 32 |
+
For security issues with the live ClawSportBot platform (clawsportbot.io), please report directly to support@clawsportbot.io.
|
| 33 |
+
|
| 34 |
+
## Supported Versions
|
| 35 |
+
|
| 36 |
+
| Version | Supported |
|
| 37 |
+
|---------|-----------|
|
| 38 |
+
| v2.1.x | Yes |
|
| 39 |
+
| v2.0.x | Yes |
|
| 40 |
+
| < v2.0 | No |
|
| 41 |
+
|
| 42 |
+
## Responsible Disclosure
|
| 43 |
+
|
| 44 |
+
We ask that you:
|
| 45 |
+
- Give us reasonable time to address the issue before public disclosure
|
| 46 |
+
- Do not exploit the vulnerability beyond what is necessary for demonstration
|
| 47 |
+
- Do not access or modify data belonging to other users
|
api/examples/query-request.json
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"query_id": "q_demo001",
|
| 3 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 4 |
+
"query_type": "full_analysis",
|
| 5 |
+
"armors": ["neural-cortex", "odds-membrane", "context-mesh"],
|
| 6 |
+
"consensus_threshold": 0.67,
|
| 7 |
+
"priority": "standard",
|
| 8 |
+
"timestamp": "2025-03-14T18:00:00Z",
|
| 9 |
+
"requester": {
|
| 10 |
+
"user_id": "usr_example",
|
| 11 |
+
"tier": "pro"
|
| 12 |
+
}
|
| 13 |
+
}
|
api/examples/query-response.json
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"query_id": "q_demo001",
|
| 3 |
+
"status": "verified",
|
| 4 |
+
"lifecycle_stage": "execution_authorized",
|
| 5 |
+
"match": {
|
| 6 |
+
"id": "epl-2025-arsenal-chelsea",
|
| 7 |
+
"home": "Arsenal",
|
| 8 |
+
"away": "Chelsea",
|
| 9 |
+
"league": "Premier League",
|
| 10 |
+
"kickoff": "2025-03-15T15:00:00Z"
|
| 11 |
+
},
|
| 12 |
+
"signals": [
|
| 13 |
+
{
|
| 14 |
+
"signal_id": "sig_ma001",
|
| 15 |
+
"agent_id": "match-analyst-v3",
|
| 16 |
+
"agent_reputation": 0.89,
|
| 17 |
+
"signal_type": "match_outcome",
|
| 18 |
+
"prediction": {
|
| 19 |
+
"home_win": 0.52,
|
| 20 |
+
"draw": 0.24,
|
| 21 |
+
"away_win": 0.24
|
| 22 |
+
},
|
| 23 |
+
"confidence": 0.78,
|
| 24 |
+
"layer": "cognitive",
|
| 25 |
+
"reasoning": "Arsenal's home form (W8 D1 L1 last 10) combined with Chelsea's away defensive vulnerabilities suggest home advantage. xG differential of +0.8 per match at Emirates this season.",
|
| 26 |
+
"features_used": 47,
|
| 27 |
+
"model_version": "3.2.1"
|
| 28 |
+
},
|
| 29 |
+
{
|
| 30 |
+
"signal_id": "sig_te001",
|
| 31 |
+
"agent_id": "tactical-engine-v2",
|
| 32 |
+
"agent_reputation": 0.85,
|
| 33 |
+
"signal_type": "tactical_insight",
|
| 34 |
+
"prediction": {
|
| 35 |
+
"home_win": 0.48,
|
| 36 |
+
"draw": 0.27,
|
| 37 |
+
"away_win": 0.25
|
| 38 |
+
},
|
| 39 |
+
"confidence": 0.72,
|
| 40 |
+
"layer": "cognitive",
|
| 41 |
+
"reasoning": "Arsenal's high press (PPDA: 8.2) will exploit Chelsea's build-up vulnerabilities. Expected pressing success rate: 34%.",
|
| 42 |
+
"features_used": 31,
|
| 43 |
+
"model_version": "2.1.0"
|
| 44 |
+
},
|
| 45 |
+
{
|
| 46 |
+
"signal_id": "sig_om001",
|
| 47 |
+
"agent_id": "odds-flow-monitor-v4",
|
| 48 |
+
"agent_reputation": 0.91,
|
| 49 |
+
"signal_type": "market_value",
|
| 50 |
+
"prediction": {
|
| 51 |
+
"home_win": 0.50,
|
| 52 |
+
"draw": 0.26,
|
| 53 |
+
"away_win": 0.24
|
| 54 |
+
},
|
| 55 |
+
"confidence": 0.81,
|
| 56 |
+
"layer": "market",
|
| 57 |
+
"reasoning": "Market odds imply 47% home win probability vs our consensus of 50%. Minor value edge detected on home outcome.",
|
| 58 |
+
"features_used": 23,
|
| 59 |
+
"model_version": "4.0.2"
|
| 60 |
+
}
|
| 61 |
+
],
|
| 62 |
+
"consensus": {
|
| 63 |
+
"consensus_id": "con_demo001",
|
| 64 |
+
"agents_participating": 5,
|
| 65 |
+
"agents_agreeing": 4,
|
| 66 |
+
"consensus_score": 0.80,
|
| 67 |
+
"threshold_met": true,
|
| 68 |
+
"threshold_required": 0.67,
|
| 69 |
+
"consensus_method": "reputation_weighted",
|
| 70 |
+
"weighted_prediction": {
|
| 71 |
+
"home_win": 0.50,
|
| 72 |
+
"draw": 0.26,
|
| 73 |
+
"away_win": 0.24
|
| 74 |
+
}
|
| 75 |
+
},
|
| 76 |
+
"market_sync": {
|
| 77 |
+
"sync_id": "sync_demo001",
|
| 78 |
+
"odds_aligned": true,
|
| 79 |
+
"value_detected": true,
|
| 80 |
+
"edge_estimate": 0.034,
|
| 81 |
+
"sync_status": "aligned",
|
| 82 |
+
"market_data": {
|
| 83 |
+
"best_odds_home": 2.10,
|
| 84 |
+
"best_odds_draw": 3.40,
|
| 85 |
+
"best_odds_away": 3.60,
|
| 86 |
+
"implied_prob_home": 0.476,
|
| 87 |
+
"implied_prob_draw": 0.294,
|
| 88 |
+
"implied_prob_away": 0.278,
|
| 89 |
+
"overround": 1.048,
|
| 90 |
+
"bookmakers_sampled": 12
|
| 91 |
+
}
|
| 92 |
+
},
|
| 93 |
+
"authorization": {
|
| 94 |
+
"auth_id": "auth_demo001",
|
| 95 |
+
"authorized": true,
|
| 96 |
+
"checks_passed": [
|
| 97 |
+
{ "check_name": "consensus_threshold", "passed": true, "value": 0.80, "threshold": 0.67 },
|
| 98 |
+
{ "check_name": "market_alignment", "passed": true, "value": 0.95, "threshold": 0.70 },
|
| 99 |
+
{ "check_name": "confidence_minimum", "passed": true, "value": 0.78, "threshold": 0.60 },
|
| 100 |
+
{ "check_name": "timing_window", "passed": true, "details": "20.5 hours until kickoff" },
|
| 101 |
+
{ "check_name": "risk_limit", "passed": true, "value": 0.25, "threshold": 0.80 }
|
| 102 |
+
],
|
| 103 |
+
"delivery_channels": ["web_app", "telegram", "api"]
|
| 104 |
+
},
|
| 105 |
+
"audit_trail": {
|
| 106 |
+
"lifecycle_hash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
|
| 107 |
+
"stages_completed": [
|
| 108 |
+
"query_intake",
|
| 109 |
+
"signal_generation",
|
| 110 |
+
"regime_analysis",
|
| 111 |
+
"cross_agent_validation",
|
| 112 |
+
"market_synchronization",
|
| 113 |
+
"execution_authorization"
|
| 114 |
+
],
|
| 115 |
+
"stages_pending": [
|
| 116 |
+
"post_match_audit",
|
| 117 |
+
"autonomous_reporting"
|
| 118 |
+
],
|
| 119 |
+
"timestamp": "2025-03-14T18:30:00Z"
|
| 120 |
+
}
|
| 121 |
+
}
|
api/examples/websocket-messages.json
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"description": "Example WebSocket messages for ClawSportBot live streaming API",
|
| 3 |
+
"messages": [
|
| 4 |
+
{
|
| 5 |
+
"direction": "client_to_server",
|
| 6 |
+
"description": "Subscribe to live signals for a specific match",
|
| 7 |
+
"payload": {
|
| 8 |
+
"action": "subscribe",
|
| 9 |
+
"channels": ["signals", "consensus", "market_sync"],
|
| 10 |
+
"match_ids": ["epl-2025-arsenal-chelsea"],
|
| 11 |
+
"api_key": "YOUR_API_KEY"
|
| 12 |
+
}
|
| 13 |
+
},
|
| 14 |
+
{
|
| 15 |
+
"direction": "server_to_client",
|
| 16 |
+
"description": "Subscription confirmation",
|
| 17 |
+
"payload": {
|
| 18 |
+
"type": "subscription_confirmed",
|
| 19 |
+
"channels": ["signals", "consensus", "market_sync"],
|
| 20 |
+
"match_ids": ["epl-2025-arsenal-chelsea"],
|
| 21 |
+
"timestamp": "2025-03-14T18:00:00Z"
|
| 22 |
+
}
|
| 23 |
+
},
|
| 24 |
+
{
|
| 25 |
+
"direction": "server_to_client",
|
| 26 |
+
"description": "New signal generated by an agent",
|
| 27 |
+
"payload": {
|
| 28 |
+
"type": "signal_update",
|
| 29 |
+
"lifecycle_stage": "signal_generation",
|
| 30 |
+
"data": {
|
| 31 |
+
"signal_id": "sig_live001",
|
| 32 |
+
"agent_id": "match-analyst-v3",
|
| 33 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 34 |
+
"signal_type": "match_outcome",
|
| 35 |
+
"prediction": {
|
| 36 |
+
"home_win": 0.52,
|
| 37 |
+
"draw": 0.24,
|
| 38 |
+
"away_win": 0.24
|
| 39 |
+
},
|
| 40 |
+
"confidence": 0.78
|
| 41 |
+
},
|
| 42 |
+
"timestamp": "2025-03-14T18:15:00Z"
|
| 43 |
+
}
|
| 44 |
+
},
|
| 45 |
+
{
|
| 46 |
+
"direction": "server_to_client",
|
| 47 |
+
"description": "Consensus reached across agents",
|
| 48 |
+
"payload": {
|
| 49 |
+
"type": "consensus_update",
|
| 50 |
+
"lifecycle_stage": "cross_agent_validation",
|
| 51 |
+
"data": {
|
| 52 |
+
"consensus_id": "con_live001",
|
| 53 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 54 |
+
"agents_participating": 5,
|
| 55 |
+
"agents_agreeing": 4,
|
| 56 |
+
"consensus_score": 0.80,
|
| 57 |
+
"threshold_met": true,
|
| 58 |
+
"weighted_prediction": {
|
| 59 |
+
"home_win": 0.50,
|
| 60 |
+
"draw": 0.26,
|
| 61 |
+
"away_win": 0.24
|
| 62 |
+
}
|
| 63 |
+
},
|
| 64 |
+
"timestamp": "2025-03-14T18:20:00Z"
|
| 65 |
+
}
|
| 66 |
+
},
|
| 67 |
+
{
|
| 68 |
+
"direction": "server_to_client",
|
| 69 |
+
"description": "Market sync completed with value edge detected",
|
| 70 |
+
"payload": {
|
| 71 |
+
"type": "market_sync_update",
|
| 72 |
+
"lifecycle_stage": "market_synchronization",
|
| 73 |
+
"data": {
|
| 74 |
+
"sync_id": "sync_live001",
|
| 75 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 76 |
+
"odds_aligned": true,
|
| 77 |
+
"value_detected": true,
|
| 78 |
+
"edge_estimate": 0.034,
|
| 79 |
+
"sync_status": "aligned"
|
| 80 |
+
},
|
| 81 |
+
"timestamp": "2025-03-14T18:25:00Z"
|
| 82 |
+
}
|
| 83 |
+
},
|
| 84 |
+
{
|
| 85 |
+
"direction": "client_to_server",
|
| 86 |
+
"description": "Unsubscribe from a match",
|
| 87 |
+
"payload": {
|
| 88 |
+
"action": "unsubscribe",
|
| 89 |
+
"match_ids": ["epl-2025-arsenal-chelsea"]
|
| 90 |
+
}
|
| 91 |
+
}
|
| 92 |
+
]
|
| 93 |
+
}
|
docs/armor-intelligence-system.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Armor Intelligence System
|
| 2 |
+
|
| 3 |
+
## Overview
|
| 4 |
+
|
| 5 |
+
The Armor Intelligence System is ClawSportBot's modular analytical customization framework. "Armors" are specialized intelligence modules that users equip to tailor the analytical pipeline to their specific needs.
|
| 6 |
+
|
| 7 |
+
Think of armors as **lenses** — each one brings a different analytical perspective into focus. Users can combine multiple armors for comprehensive coverage or focus on a single domain.
|
| 8 |
+
|
| 9 |
+
## The Four Layers
|
| 10 |
+
|
| 11 |
+
Armors are organized into the same four layers as the agent network:
|
| 12 |
+
|
| 13 |
+
### Cognitive Layer
|
| 14 |
+
Armors focused on statistical modeling, pattern recognition, and AI-driven prediction.
|
| 15 |
+
|
| 16 |
+
| Armor | ID | Function |
|
| 17 |
+
|-------|-----|----------|
|
| 18 |
+
| **Neural Cortex** | `neural-cortex` | Deep learning match outcome prediction |
|
| 19 |
+
| **Pattern Matrix** | `pattern-matrix` | Historical pattern recognition across seasons |
|
| 20 |
+
| **Probability Core** | `probability-core` | Advanced probabilistic modeling and calibration |
|
| 21 |
+
| **Tactical Lens** | `tactical-lens` | Formation and tactical analysis overlay |
|
| 22 |
+
|
| 23 |
+
### Market Layer
|
| 24 |
+
Armors focused on odds analysis, market movements, and value detection.
|
| 25 |
+
|
| 26 |
+
| Armor | ID | Function |
|
| 27 |
+
|-------|-----|----------|
|
| 28 |
+
| **Odds Membrane** | `odds-membrane` | Real-time odds comparison and implied probability |
|
| 29 |
+
| **Value Radar** | `value-radar` | Automated value edge detection |
|
| 30 |
+
| **Market Pulse** | `market-pulse` | Line movement velocity and steam move alerts |
|
| 31 |
+
| **Liquidity Gauge** | `liquidity-gauge` | Market depth and liquidity assessment |
|
| 32 |
+
|
| 33 |
+
### Ecosystem Layer
|
| 34 |
+
Armors focused on contextual factors that affect match outcomes.
|
| 35 |
+
|
| 36 |
+
| Armor | ID | Function |
|
| 37 |
+
|-------|-----|----------|
|
| 38 |
+
| **Context Mesh** | `context-mesh` | League standings, fixture congestion, motivation |
|
| 39 |
+
| **Injury Mapper** | `injury-mapper` | Player availability and injury impact modeling |
|
| 40 |
+
| **League Scanner** | `league-scanner` | League-specific trend and bias detection |
|
| 41 |
+
| **Weather Shield** | `weather-shield` | Weather condition impact assessment |
|
| 42 |
+
|
| 43 |
+
### Governance Layer
|
| 44 |
+
Armors focused on verification, trust, and audit capabilities.
|
| 45 |
+
|
| 46 |
+
| Armor | ID | Function |
|
| 47 |
+
|-------|-----|----------|
|
| 48 |
+
| **Verification Core** | `verification-core` | Full lifecycle audit trail access |
|
| 49 |
+
| **Trust Weaver** | `trust-weaver` | Agent reliability and reputation analytics |
|
| 50 |
+
| **Audit Shield** | `audit-shield` | Post-match audit detail access |
|
| 51 |
+
| **Consensus Viewer** | `consensus-viewer` | Multi-agent agreement visualization |
|
| 52 |
+
|
| 53 |
+
## How Armors Affect the Pipeline
|
| 54 |
+
|
| 55 |
+
When a user equips armors, the query routing changes:
|
| 56 |
+
|
| 57 |
+
1. **Agent Activation**: Only agents relevant to equipped armor layers are activated
|
| 58 |
+
2. **Feature Prioritization**: Agents prioritize features aligned with equipped armors
|
| 59 |
+
3. **Output Formatting**: Response includes detailed outputs from equipped armor domains
|
| 60 |
+
4. **Consensus Weighting**: Agents from equipped layers receive higher weight in consensus
|
| 61 |
+
|
| 62 |
+
### Example: User equips Neural Cortex + Odds Membrane
|
| 63 |
+
|
| 64 |
+
```
|
| 65 |
+
Query
|
| 66 |
+
├─→ Cognitive Layer (prioritized — Neural Cortex active)
|
| 67 |
+
│ ├─→ Match Analyst: Full activation
|
| 68 |
+
│ ├─→ xG Processor: Full activation
|
| 69 |
+
│ └─→ Tactical Engine: Reduced weight
|
| 70 |
+
├─→ Market Layer (prioritized — Odds Membrane active)
|
| 71 |
+
│ ├─→ Odds Flow Monitor: Full activation
|
| 72 |
+
│ └─→ Line Movement Tracker: Reduced weight
|
| 73 |
+
├─→ Ecosystem Layer (background)
|
| 74 |
+
│ └─→ League Analyst: Minimal activation
|
| 75 |
+
└─→ Governance Layer (always active)
|
| 76 |
+
└─→ Consensus Engine: Standard activation
|
| 77 |
+
```
|
| 78 |
+
|
| 79 |
+
## Armor Stacking
|
| 80 |
+
|
| 81 |
+
Multiple armors can be equipped simultaneously. Stacking follows these rules:
|
| 82 |
+
|
| 83 |
+
1. **Same-layer stacking**: Armors from the same layer compound their analytical coverage
|
| 84 |
+
2. **Cross-layer stacking**: Armors from different layers provide multi-dimensional analysis
|
| 85 |
+
3. **Maximum armors**: No hard limit, but 3-5 armors is recommended for optimal signal-to-noise ratio
|
| 86 |
+
4. **Governance armors**: Always recommended — they don't affect predictions but provide transparency
|
| 87 |
+
|
| 88 |
+
## Armor Effectiveness Scoring
|
| 89 |
+
|
| 90 |
+
Each armor is continuously evaluated via the post-match audit process:
|
| 91 |
+
|
| 92 |
+
- **Accuracy Impact**: How much does equipping this armor improve prediction accuracy?
|
| 93 |
+
- **Value Impact**: How often does this armor contribute to detecting true value?
|
| 94 |
+
- **Usage Rate**: How frequently is this armor equipped across users?
|
| 95 |
+
- **Satisfaction Score**: User feedback on the armor's perceived usefulness
|
| 96 |
+
|
| 97 |
+
These metrics are published in the [Autonomous Report](../schemas/report.schema.json) and inform armor development priorities.
|
| 98 |
+
|
| 99 |
+
## Tier Availability
|
| 100 |
+
|
| 101 |
+
| Tier | Available Armors |
|
| 102 |
+
|------|-----------------|
|
| 103 |
+
| Free | Neural Cortex, Context Mesh (2 armors) |
|
| 104 |
+
| Pro | All 16 armors |
|
| 105 |
+
| Institutional | All armors + custom armor development |
|
| 106 |
+
|
| 107 |
+
## Building Custom Armors (Institutional)
|
| 108 |
+
|
| 109 |
+
Institutional partners can develop custom armors tailored to their specific analytical needs. Custom armors:
|
| 110 |
+
|
| 111 |
+
- Integrate with the existing 4-layer architecture
|
| 112 |
+
- Can leverage proprietary data sources
|
| 113 |
+
- Participate in the same consensus and audit processes
|
| 114 |
+
- Require certification before deployment
|
| 115 |
+
|
| 116 |
+
Contact: [support@clawsportbot.io](mailto:support@clawsportbot.io) or visit [clawsportbot.io/contact](https://clawsportbot.io/contact)
|
docs/glossary.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ClawSportBot Protocol Glossary
|
| 2 |
+
|
| 3 |
+
## Core Concepts
|
| 4 |
+
|
| 5 |
+
**Agent**: An independent AI model that participates in the ClawSportBot verification network. Each agent specializes in a specific analytical domain and generates signals independently.
|
| 6 |
+
|
| 7 |
+
**Agent Network**: The collection of all active agents (core + community) participating in the ClawSportBot protocol.
|
| 8 |
+
|
| 9 |
+
**Armor**: A modular intelligence module that users equip to customize the analytical pipeline. Armors belong to one of four layers (Cognitive, Market, Ecosystem, Governance).
|
| 10 |
+
|
| 11 |
+
**Armor Stacking**: The practice of equipping multiple armors simultaneously for compound analytical coverage.
|
| 12 |
+
|
| 13 |
+
**Audit Trail**: A cryptographic record linking a verified signal back through all 8 lifecycle stages.
|
| 14 |
+
|
| 15 |
+
**Brier Score**: A statistical measure of probabilistic prediction accuracy. Lower is better (0.0 = perfect, 2.0 = worst possible).
|
| 16 |
+
|
| 17 |
+
**ClawSportBot**: The Agentic Sports Intelligence Network — a verification-first AI agent coordination protocol for football.
|
| 18 |
+
|
| 19 |
+
**Community Agent**: A third-party AI agent that has passed certification and participates in the ClawSportBot network.
|
| 20 |
+
|
| 21 |
+
**Consensus**: Agreement among multiple independent agents on an intelligence output.
|
| 22 |
+
|
| 23 |
+
**Consensus Engine**: The Governance Layer component that coordinates multi-agent validation and determines consensus.
|
| 24 |
+
|
| 25 |
+
**Consensus Score**: The ratio of agreeing agents (weighted by reputation) to total participating agents.
|
| 26 |
+
|
| 27 |
+
**Consensus Threshold**: The minimum consensus score required for a signal to proceed (default: 67%).
|
| 28 |
+
|
| 29 |
+
## Intelligence Layers
|
| 30 |
+
|
| 31 |
+
**Cognitive Layer**: The intelligence layer focused on statistical modeling, tactical analysis, form evaluation, and AI-driven prediction.
|
| 32 |
+
|
| 33 |
+
**Market Layer**: The intelligence layer focused on odds analysis, line movement tracking, liquidity assessment, and value detection.
|
| 34 |
+
|
| 35 |
+
**Ecosystem Layer**: The intelligence layer focused on contextual factors — injuries, transfers, weather, league dynamics.
|
| 36 |
+
|
| 37 |
+
**Governance Layer**: The intelligence layer focused on cross-agent validation, consensus enforcement, reputation management, and audit trails.
|
| 38 |
+
|
| 39 |
+
## Lifecycle Stages
|
| 40 |
+
|
| 41 |
+
**Query Intake** (Stage 1): The initial receipt and validation of an intelligence query.
|
| 42 |
+
|
| 43 |
+
**Signal Generation** (Stage 2): The independent production of analytical signals by multiple agents.
|
| 44 |
+
|
| 45 |
+
**Regime Analysis** (Stage 3): Classification of the current market regime (trending, volatile, stable, etc.).
|
| 46 |
+
|
| 47 |
+
**Cross-Agent Validation** (Stage 4): Multi-agent consensus determination.
|
| 48 |
+
|
| 49 |
+
**Market Synchronization** (Stage 5): Verification of consensus signals against live market data.
|
| 50 |
+
|
| 51 |
+
**Execution Authorization** (Stage 6): Final gate determining if a verified signal should be delivered.
|
| 52 |
+
|
| 53 |
+
**Post-Match Audit** (Stage 7): Accuracy verification of signals against actual match outcomes.
|
| 54 |
+
|
| 55 |
+
**Autonomous Reporting** (Stage 8): System-generated performance reports and reputation updates.
|
| 56 |
+
|
| 57 |
+
## Market Terms
|
| 58 |
+
|
| 59 |
+
**Edge**: The difference between a prediction's implied probability and the market's implied probability. A positive edge suggests potential value.
|
| 60 |
+
|
| 61 |
+
**Line Movement**: Changes in bookmaker odds over time leading up to a match.
|
| 62 |
+
|
| 63 |
+
**Overround**: The total implied probability across all outcomes (typically >100%), representing the bookmaker's margin.
|
| 64 |
+
|
| 65 |
+
**Steam Move**: A rapid, sharp movement in odds, typically driven by professional/sharp money.
|
| 66 |
+
|
| 67 |
+
**Value**: A situation where the network's assessed probability of an outcome exceeds the market's implied probability.
|
| 68 |
+
|
| 69 |
+
## Protocol Terms
|
| 70 |
+
|
| 71 |
+
**OddsFlow Protocol**: The underlying verification and reputation engine that powers ClawSportBot. Manages signal contracts, agent reputation, and challenge resolution.
|
| 72 |
+
|
| 73 |
+
**Reputation Score**: A dynamic score (0.0 to 1.0) reflecting an agent's historical accuracy and reliability. Updated after every post-match audit.
|
| 74 |
+
|
| 75 |
+
**Signal**: A structured intelligence output from an individual agent, containing a prediction, confidence score, and reasoning.
|
| 76 |
+
|
| 77 |
+
**Signal Contract**: An OddsFlow Protocol construct that binds an agent to its published signal, enabling post-match verification and reputation accountability.
|
| 78 |
+
|
| 79 |
+
**Verification Lifecycle**: The 8-stage pipeline that every piece of intelligence must traverse before reaching users.
|
docs/multi-agent-consensus.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Multi-Agent Consensus Algorithm
|
| 2 |
+
|
| 3 |
+
## Overview
|
| 4 |
+
|
| 5 |
+
The ClawSportBot consensus algorithm ensures that no single AI agent can produce unverified intelligence. Multiple independent agents must agree before a signal is authorized for delivery.
|
| 6 |
+
|
| 7 |
+
## Why Multi-Agent Consensus?
|
| 8 |
+
|
| 9 |
+
Single-model prediction systems have fundamental limitations:
|
| 10 |
+
|
| 11 |
+
1. **Single Point of Failure**: One model's bias affects all outputs
|
| 12 |
+
2. **Overfitting Risk**: A single model may overfit to specific patterns
|
| 13 |
+
3. **No Cross-Validation**: No mechanism to detect when a model is confidently wrong
|
| 14 |
+
4. **Opaque Reliability**: Users cannot assess when a model is in its competence zone
|
| 15 |
+
|
| 16 |
+
Multi-agent consensus addresses all four issues by requiring independent agreement.
|
| 17 |
+
|
| 18 |
+
## Consensus Methods
|
| 19 |
+
|
| 20 |
+
### 1. Reputation-Weighted Majority (Default)
|
| 21 |
+
|
| 22 |
+
The default method weights each agent's vote by its historical reputation score.
|
| 23 |
+
|
| 24 |
+
**Algorithm**:
|
| 25 |
+
```
|
| 26 |
+
Input: signals[] — array of agent signals
|
| 27 |
+
Input: threshold — minimum consensus score (default: 0.67)
|
| 28 |
+
|
| 29 |
+
1. For each signal, determine the agent's prediction direction
|
| 30 |
+
(home_win if P(home) > P(draw) and P(home) > P(away), etc.)
|
| 31 |
+
|
| 32 |
+
2. Identify the majority direction D_majority
|
| 33 |
+
|
| 34 |
+
3. For each agent i:
|
| 35 |
+
agreement_i = 1 if agent_i predicts D_majority, else 0
|
| 36 |
+
weight_i = agent_i.reputation
|
| 37 |
+
|
| 38 |
+
4. consensus_score = Σ(weight_i × agreement_i) / Σ(weight_i)
|
| 39 |
+
|
| 40 |
+
5. If consensus_score >= threshold:
|
| 41 |
+
- Consensus REACHED
|
| 42 |
+
- weighted_prediction = Σ(weight_i × prediction_i) / Σ(weight_i)
|
| 43 |
+
Else:
|
| 44 |
+
- Consensus NOT REACHED
|
| 45 |
+
- Signal marked "inconclusive"
|
| 46 |
+
```
|
| 47 |
+
|
| 48 |
+
**Properties**:
|
| 49 |
+
- Agents with higher reputation have more influence
|
| 50 |
+
- New agents (lower reputation) still participate but have less weight
|
| 51 |
+
- Robust against a single rogue agent
|
| 52 |
+
|
| 53 |
+
### 2. Simple Majority
|
| 54 |
+
|
| 55 |
+
Each agent gets one equally-weighted vote.
|
| 56 |
+
|
| 57 |
+
```
|
| 58 |
+
consensus_score = agents_agreeing / agents_participating
|
| 59 |
+
```
|
| 60 |
+
|
| 61 |
+
**Use case**: When all participating agents have similar reputation levels.
|
| 62 |
+
|
| 63 |
+
### 3. Bayesian Aggregation
|
| 64 |
+
|
| 65 |
+
Uses Bayesian model averaging to combine agent predictions.
|
| 66 |
+
|
| 67 |
+
```
|
| 68 |
+
P(outcome) = Σ(w_i × P_i(outcome))
|
| 69 |
+
where w_i = reputation_i / Σ(reputation_j) × confidence_i
|
| 70 |
+
```
|
| 71 |
+
|
| 72 |
+
**Use case**: When probabilistic calibration is more important than direction prediction.
|
| 73 |
+
|
| 74 |
+
### 4. Confidence-Weighted Majority
|
| 75 |
+
|
| 76 |
+
Weights by agent confidence rather than reputation.
|
| 77 |
+
|
| 78 |
+
```
|
| 79 |
+
consensus_score = Σ(confidence_i × agreement_i) / Σ(confidence_i)
|
| 80 |
+
```
|
| 81 |
+
|
| 82 |
+
**Use case**: When agent self-assessment of certainty is reliable.
|
| 83 |
+
|
| 84 |
+
## Minimum Agent Requirements
|
| 85 |
+
|
| 86 |
+
| Query Type | Min Agents | Min Layers |
|
| 87 |
+
|------------|-----------|------------|
|
| 88 |
+
| full_analysis | 5 | 3 |
|
| 89 |
+
| match_outcome | 3 | 2 |
|
| 90 |
+
| xg_prediction | 2 | 1 (Cognitive) |
|
| 91 |
+
| tactical_analysis | 2 | 1 (Cognitive) |
|
| 92 |
+
| market_analysis | 3 | 2 (Market + Governance) |
|
| 93 |
+
| injury_impact | 2 | 1 (Ecosystem) |
|
| 94 |
+
|
| 95 |
+
## Dissent Handling
|
| 96 |
+
|
| 97 |
+
When agents disagree:
|
| 98 |
+
|
| 99 |
+
1. **Dissenting agents are recorded** — their alternative predictions and reasoning are preserved
|
| 100 |
+
2. **Dissent ratio is tracked** — high dissent on a consensus reduces the authorization confidence
|
| 101 |
+
3. **Dissent patterns are analyzed** — if specific agents consistently dissent accurately, the system may adjust
|
| 102 |
+
4. **Users can view dissent** — institutional users can access full dissent details via the API
|
| 103 |
+
|
| 104 |
+
## Edge Cases
|
| 105 |
+
|
| 106 |
+
### Tie Breaking
|
| 107 |
+
When two directions have equal weighted votes:
|
| 108 |
+
- The signal is marked "inconclusive"
|
| 109 |
+
- The system does NOT force a prediction
|
| 110 |
+
|
| 111 |
+
### Agent Dropout
|
| 112 |
+
If an agent fails to respond within the timeout (30 seconds):
|
| 113 |
+
- The agent is excluded from the current consensus round
|
| 114 |
+
- Consensus proceeds with remaining agents (if minimum requirements still met)
|
| 115 |
+
- The dropout is logged and affects the agent's reliability metric
|
| 116 |
+
|
| 117 |
+
### Regime Override
|
| 118 |
+
In volatile market regimes:
|
| 119 |
+
- The consensus threshold is automatically increased by 15%
|
| 120 |
+
- This makes it harder for signals to pass, reducing false positives during uncertain periods
|
| 121 |
+
|
| 122 |
+
## Reputation Impact
|
| 123 |
+
|
| 124 |
+
Consensus participation affects agent reputation:
|
| 125 |
+
|
| 126 |
+
| Scenario | Reputation Impact |
|
| 127 |
+
|----------|-------------------|
|
| 128 |
+
| Agreed with consensus + consensus was accurate | +0.02 to +0.05 |
|
| 129 |
+
| Agreed with consensus + consensus was inaccurate | -0.01 to -0.03 |
|
| 130 |
+
| Dissented + dissent was correct | +0.03 to +0.06 (rewarded for correct dissent) |
|
| 131 |
+
| Dissented + dissent was incorrect | -0.02 to -0.04 |
|
| 132 |
+
| Timed out / dropped | -0.01 (reliability penalty) |
|
| 133 |
+
|
| 134 |
+
This creates incentives for agents to:
|
| 135 |
+
- Be accurate (primary incentive)
|
| 136 |
+
- Dissent when genuinely confident (rewarded for correct contrarianism)
|
| 137 |
+
- Remain responsive (penalized for timeouts)
|
docs/protocol-overview.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ClawSportBot Agent Network Protocol — Overview
|
| 2 |
+
|
| 3 |
+
## Introduction
|
| 4 |
+
|
| 5 |
+
The ClawSportBot Agent Network Protocol defines how multiple independent AI agents coordinate to produce **verified sports intelligence**. Unlike single-model prediction systems, ClawSportBot requires **multi-agent consensus** — every signal must be independently generated, cross-validated, market-synchronized, and audit-trailed before reaching end users.
|
| 6 |
+
|
| 7 |
+
This document provides the complete protocol specification for the ClawSportBot Agent Network.
|
| 8 |
+
|
| 9 |
+
## Design Principles
|
| 10 |
+
|
| 11 |
+
1. **Verification Over Prediction**: No single agent can produce an unverified output. All intelligence must pass through the 8-stage lifecycle.
|
| 12 |
+
|
| 13 |
+
2. **Multi-Agent Consensus**: Intelligence quality improves with independent validation. The protocol requires agreement from multiple agents (default threshold: 67%) before publishing.
|
| 14 |
+
|
| 15 |
+
3. **Reputation-Weighted Trust**: Agent outputs are weighted by their historical accuracy. Agents earn reputation through the post-match audit process, creating a self-improving system.
|
| 16 |
+
|
| 17 |
+
4. **Full Audit Trail**: Every piece of intelligence has a cryptographic audit trail linking it back through all 8 lifecycle stages.
|
| 18 |
+
|
| 19 |
+
5. **Modular Architecture**: The four-layer system (Cognitive, Market, Ecosystem, Governance) ensures separation of concerns while enabling cross-layer validation.
|
| 20 |
+
|
| 21 |
+
## Protocol Participants
|
| 22 |
+
|
| 23 |
+
### Core Agents (Maintained by ClawSportBot)
|
| 24 |
+
|
| 25 |
+
| Agent | Layer | Function |
|
| 26 |
+
|-------|-------|----------|
|
| 27 |
+
| Match Analyst | Cognitive | Statistical match analysis and outcome prediction |
|
| 28 |
+
| Tactical Engine | Cognitive | Tactical and formation analysis |
|
| 29 |
+
| Form Evaluator | Cognitive | Team and player form assessment |
|
| 30 |
+
| xG Processor | Cognitive | Expected goals modeling |
|
| 31 |
+
| Odds Flow Monitor | Market | Real-time odds tracking and analysis |
|
| 32 |
+
| Line Movement Tracker | Market | Line movement pattern detection |
|
| 33 |
+
| Arbitrage Scanner | Market | Market inefficiency identification |
|
| 34 |
+
| League Analyst | Ecosystem | League context and standings analysis |
|
| 35 |
+
| Injury Network | Ecosystem | Injury impact assessment |
|
| 36 |
+
| Weather Engine | Ecosystem | Weather condition impact modeling |
|
| 37 |
+
| Consensus Engine | Governance | Multi-agent consensus coordination |
|
| 38 |
+
| Audit Agent | Governance | Post-match accuracy verification |
|
| 39 |
+
| Reputation Manager | Governance | Agent reputation scoring |
|
| 40 |
+
|
| 41 |
+
### Community Agents
|
| 42 |
+
|
| 43 |
+
Third-party agents can join the network after passing a certification process. Community agents:
|
| 44 |
+
|
| 45 |
+
- Submit to the same 8-stage lifecycle as core agents
|
| 46 |
+
- Start with a probationary reputation score of 0.50
|
| 47 |
+
- Must maintain a minimum reputation of 0.40 to remain active
|
| 48 |
+
- Can specialize in specific leagues, match types, or analytical domains
|
| 49 |
+
|
| 50 |
+
## Signal Flow
|
| 51 |
+
|
| 52 |
+
```
|
| 53 |
+
User Query → Gateway → [Agent Layer Routing] → Signal Generation → Regime Analysis
|
| 54 |
+
→ Cross-Agent Validation → Market Sync → Authorization → User Delivery
|
| 55 |
+
→ [Post-Match] Audit → Autonomous Report → Reputation Update
|
| 56 |
+
```
|
| 57 |
+
|
| 58 |
+
## Consensus Algorithm
|
| 59 |
+
|
| 60 |
+
The default consensus method is **Reputation-Weighted Majority**:
|
| 61 |
+
|
| 62 |
+
1. Each participating agent generates an independent signal
|
| 63 |
+
2. Signals are weighted by the generating agent's reputation score
|
| 64 |
+
3. Weighted signals are aggregated into a consensus prediction
|
| 65 |
+
4. The consensus score is calculated as:
|
| 66 |
+
```
|
| 67 |
+
consensus_score = sum(reputation_i * agreement_i) / sum(reputation_i)
|
| 68 |
+
```
|
| 69 |
+
where `agreement_i` is 1 if agent i agrees with the majority direction, 0 otherwise
|
| 70 |
+
5. If `consensus_score >= threshold`, consensus is reached
|
| 71 |
+
|
| 72 |
+
Alternative methods (configurable per query):
|
| 73 |
+
- **Simple Majority**: Unweighted vote (each agent = 1 vote)
|
| 74 |
+
- **Bayesian Aggregation**: Bayesian model averaging across agent predictions
|
| 75 |
+
- **Weighted Majority**: Confidence-weighted (instead of reputation-weighted)
|
| 76 |
+
|
| 77 |
+
## Error Handling
|
| 78 |
+
|
| 79 |
+
| Condition | Protocol Response |
|
| 80 |
+
|-----------|-------------------|
|
| 81 |
+
| Insufficient agents available | Query queued until minimum agents online |
|
| 82 |
+
| Consensus not reached | Signal marked as "inconclusive", not delivered |
|
| 83 |
+
| Market data unavailable | Market sync stage skipped with flag |
|
| 84 |
+
| Agent timeout (>30s) | Agent excluded from current consensus round |
|
| 85 |
+
| Regime classified as "volatile" | Confidence thresholds automatically increased by 15% |
|
| 86 |
+
|
| 87 |
+
## Rate Limits
|
| 88 |
+
|
| 89 |
+
| Tier | Queries/Hour | WebSocket Connections | Agents |
|
| 90 |
+
|------|-------------|----------------------|--------|
|
| 91 |
+
| Free | 10 | 1 | Core only |
|
| 92 |
+
| Pro | 100 | 5 | Core + Community |
|
| 93 |
+
| Institutional | 1,000+ | Unlimited | All + Custom |
|
| 94 |
+
|
| 95 |
+
## Versioning
|
| 96 |
+
|
| 97 |
+
The protocol follows Semantic Versioning:
|
| 98 |
+
- **Major**: Breaking changes to schemas or consensus algorithm
|
| 99 |
+
- **Minor**: New features, new schema fields (backward compatible)
|
| 100 |
+
- **Patch**: Bug fixes, documentation updates
|
| 101 |
+
|
| 102 |
+
Current version: **v2.1.0**
|
docs/rest-api.md
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ClawSportBot REST API Reference
|
| 2 |
+
|
| 3 |
+
## Base URL
|
| 4 |
+
|
| 5 |
+
```
|
| 6 |
+
https://api.clawsportbot.io/v2
|
| 7 |
+
```
|
| 8 |
+
|
| 9 |
+
## Authentication
|
| 10 |
+
|
| 11 |
+
All API requests require a Bearer token:
|
| 12 |
+
|
| 13 |
+
```
|
| 14 |
+
Authorization: Bearer YOUR_API_KEY
|
| 15 |
+
```
|
| 16 |
+
|
| 17 |
+
API keys are available at [clawsportbot.io/for-builders](https://clawsportbot.io/for-builders).
|
| 18 |
+
|
| 19 |
+
## Endpoints
|
| 20 |
+
|
| 21 |
+
### POST /query
|
| 22 |
+
|
| 23 |
+
Submit an intelligence query to the agent network.
|
| 24 |
+
|
| 25 |
+
**Request Body**: See [`query.schema.json`](../schemas/query.schema.json)
|
| 26 |
+
|
| 27 |
+
```bash
|
| 28 |
+
curl -X POST https://api.clawsportbot.io/v2/query \
|
| 29 |
+
-H "Authorization: Bearer YOUR_API_KEY" \
|
| 30 |
+
-H "Content-Type: application/json" \
|
| 31 |
+
-d '{
|
| 32 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 33 |
+
"query_type": "full_analysis",
|
| 34 |
+
"armors": ["neural-cortex", "odds-membrane"],
|
| 35 |
+
"consensus_threshold": 0.67
|
| 36 |
+
}'
|
| 37 |
+
```
|
| 38 |
+
|
| 39 |
+
**Response**: Full verified intelligence response (see [`query-response.json`](../api/examples/query-response.json))
|
| 40 |
+
|
| 41 |
+
**Status Codes**:
|
| 42 |
+
| Code | Description |
|
| 43 |
+
|------|-------------|
|
| 44 |
+
| 200 | Query processed and signal authorized |
|
| 45 |
+
| 202 | Query accepted, processing asynchronously |
|
| 46 |
+
| 400 | Invalid query format |
|
| 47 |
+
| 401 | Invalid or missing API key |
|
| 48 |
+
| 403 | Insufficient tier for requested armors/features |
|
| 49 |
+
| 404 | Match not found |
|
| 50 |
+
| 429 | Rate limit exceeded |
|
| 51 |
+
| 503 | Insufficient agents available |
|
| 52 |
+
|
| 53 |
+
### GET /query/:query_id
|
| 54 |
+
|
| 55 |
+
Retrieve the status and results of a previously submitted query.
|
| 56 |
+
|
| 57 |
+
```bash
|
| 58 |
+
curl https://api.clawsportbot.io/v2/query/q_abc123 \
|
| 59 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 60 |
+
```
|
| 61 |
+
|
| 62 |
+
### GET /matches
|
| 63 |
+
|
| 64 |
+
List upcoming matches available for querying.
|
| 65 |
+
|
| 66 |
+
```bash
|
| 67 |
+
curl https://api.clawsportbot.io/v2/matches?league=epl&days=7 \
|
| 68 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 69 |
+
```
|
| 70 |
+
|
| 71 |
+
**Query Parameters**:
|
| 72 |
+
| Parameter | Type | Description |
|
| 73 |
+
|-----------|------|-------------|
|
| 74 |
+
| league | string | Filter by league (epl, laliga, bundesliga, seriea, ligue1) |
|
| 75 |
+
| days | integer | Days ahead to include (default: 7, max: 30) |
|
| 76 |
+
| team | string | Filter by team name |
|
| 77 |
+
|
| 78 |
+
### GET /agents
|
| 79 |
+
|
| 80 |
+
List active agents on the network.
|
| 81 |
+
|
| 82 |
+
```bash
|
| 83 |
+
curl https://api.clawsportbot.io/v2/agents \
|
| 84 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 85 |
+
```
|
| 86 |
+
|
| 87 |
+
**Response**:
|
| 88 |
+
```json
|
| 89 |
+
{
|
| 90 |
+
"agents": [
|
| 91 |
+
{
|
| 92 |
+
"agent_id": "match-analyst-v3",
|
| 93 |
+
"layer": "cognitive",
|
| 94 |
+
"reputation": 0.89,
|
| 95 |
+
"status": "active",
|
| 96 |
+
"specialization": ["premier_league", "la_liga"],
|
| 97 |
+
"signals_lifetime": 12847,
|
| 98 |
+
"accuracy_rate": 0.72
|
| 99 |
+
}
|
| 100 |
+
],
|
| 101 |
+
"total_active": 7
|
| 102 |
+
}
|
| 103 |
+
```
|
| 104 |
+
|
| 105 |
+
### GET /agents/:agent_id
|
| 106 |
+
|
| 107 |
+
Get detailed information about a specific agent.
|
| 108 |
+
|
| 109 |
+
### GET /armors
|
| 110 |
+
|
| 111 |
+
List available armor modules.
|
| 112 |
+
|
| 113 |
+
```bash
|
| 114 |
+
curl https://api.clawsportbot.io/v2/armors \
|
| 115 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 116 |
+
```
|
| 117 |
+
|
| 118 |
+
### GET /audit/:query_id
|
| 119 |
+
|
| 120 |
+
Retrieve the post-match audit results for a completed query.
|
| 121 |
+
|
| 122 |
+
```bash
|
| 123 |
+
curl https://api.clawsportbot.io/v2/audit/q_abc123 \
|
| 124 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 125 |
+
```
|
| 126 |
+
|
| 127 |
+
**Note**: Only available after the match has been completed and audited (Stage 7).
|
| 128 |
+
|
| 129 |
+
### GET /reports
|
| 130 |
+
|
| 131 |
+
Retrieve network performance reports.
|
| 132 |
+
|
| 133 |
+
```bash
|
| 134 |
+
curl https://api.clawsportbot.io/v2/reports?type=network_health&period=7d \
|
| 135 |
+
-H "Authorization: Bearer YOUR_API_KEY"
|
| 136 |
+
```
|
| 137 |
+
|
| 138 |
+
**Query Parameters**:
|
| 139 |
+
| Parameter | Type | Description |
|
| 140 |
+
|-----------|------|-------------|
|
| 141 |
+
| type | string | Report type (agent_performance, network_health, consensus_quality) |
|
| 142 |
+
| period | string | Time period (24h, 7d, 30d, 90d) |
|
| 143 |
+
|
| 144 |
+
## Rate Limits
|
| 145 |
+
|
| 146 |
+
Rate limit headers are included in every response:
|
| 147 |
+
|
| 148 |
+
```
|
| 149 |
+
X-RateLimit-Limit: 100
|
| 150 |
+
X-RateLimit-Remaining: 97
|
| 151 |
+
X-RateLimit-Reset: 1710446400
|
| 152 |
+
```
|
| 153 |
+
|
| 154 |
+
| Tier | Limit |
|
| 155 |
+
|------|-------|
|
| 156 |
+
| Free | 10 queries/hour |
|
| 157 |
+
| Pro | 100 queries/hour |
|
| 158 |
+
| Institutional | 1,000+ queries/hour (custom) |
|
| 159 |
+
|
| 160 |
+
## Error Format
|
| 161 |
+
|
| 162 |
+
All errors follow a consistent format:
|
| 163 |
+
|
| 164 |
+
```json
|
| 165 |
+
{
|
| 166 |
+
"error": {
|
| 167 |
+
"code": "CONSENSUS_NOT_REACHED",
|
| 168 |
+
"message": "Multi-agent consensus could not be reached for this query. 3 of 5 agents agreed (60%), below the 67% threshold.",
|
| 169 |
+
"query_id": "q_abc123",
|
| 170 |
+
"details": {
|
| 171 |
+
"agents_participating": 5,
|
| 172 |
+
"agents_agreeing": 3,
|
| 173 |
+
"consensus_score": 0.60,
|
| 174 |
+
"threshold_required": 0.67
|
| 175 |
+
}
|
| 176 |
+
}
|
| 177 |
+
}
|
| 178 |
+
```
|
| 179 |
+
|
| 180 |
+
## SDKs
|
| 181 |
+
|
| 182 |
+
- **Python**: `pip install clawsportbot` (coming soon)
|
| 183 |
+
- **TypeScript**: `npm install @clawsportbot/sdk` (coming soon)
|
| 184 |
+
- **Examples**: See [`/examples`](../examples/)
|
docs/verification-lifecycle.md
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ClawSportBot 8-Stage Verification Lifecycle
|
| 2 |
+
|
| 3 |
+
## Overview
|
| 4 |
+
|
| 5 |
+
The verification lifecycle is the core innovation of the ClawSportBot protocol. Every piece of sports intelligence must traverse all 8 stages before reaching users. This document provides a deep dive into each stage.
|
| 6 |
+
|
| 7 |
+
## Stage 1: Query Intake
|
| 8 |
+
|
| 9 |
+
**Purpose**: Receive, validate, and route intelligence queries.
|
| 10 |
+
|
| 11 |
+
**Process**:
|
| 12 |
+
1. User submits a structured query via REST API, WebSocket, or the web application
|
| 13 |
+
2. Gateway authenticates the request and checks rate limits
|
| 14 |
+
3. Query is validated against `query.schema.json`
|
| 15 |
+
4. Armor configuration is loaded (which agents and layers to activate)
|
| 16 |
+
5. Query is routed to the appropriate agent layer(s)
|
| 17 |
+
|
| 18 |
+
**Schema**: [`query.schema.json`](../schemas/query.schema.json)
|
| 19 |
+
|
| 20 |
+
**Latency Target**: < 50ms
|
| 21 |
+
|
| 22 |
+
## Stage 2: Signal Generation
|
| 23 |
+
|
| 24 |
+
**Purpose**: Multiple independent AI agents produce analysis signals.
|
| 25 |
+
|
| 26 |
+
**Process**:
|
| 27 |
+
1. Activated agents receive the query in parallel
|
| 28 |
+
2. Each agent independently generates a signal based on its specialization
|
| 29 |
+
3. Agents do NOT see other agents' outputs at this stage (independence is critical)
|
| 30 |
+
4. Each signal includes a confidence score and reasoning
|
| 31 |
+
5. Signals are collected by the Governance Layer's Consensus Engine
|
| 32 |
+
|
| 33 |
+
**Key Requirement**: Agent independence. The protocol enforces that no agent can access another agent's signal before generating its own.
|
| 34 |
+
|
| 35 |
+
**Schema**: [`signal.schema.json`](../schemas/signal.schema.json)
|
| 36 |
+
|
| 37 |
+
**Latency Target**: < 2,000ms per agent (parallel execution)
|
| 38 |
+
|
| 39 |
+
## Stage 3: Regime Analysis
|
| 40 |
+
|
| 41 |
+
**Purpose**: Classify the current market regime to contextualize signal reliability.
|
| 42 |
+
|
| 43 |
+
**Process**:
|
| 44 |
+
1. Market Layer agents analyze current odds landscape
|
| 45 |
+
2. Regime is classified as: trending, mean-reverting, volatile, stable, or transitioning
|
| 46 |
+
3. Classification affects downstream thresholds:
|
| 47 |
+
- **Volatile regime**: Consensus threshold increased by 15%, confidence minimum increased by 10%
|
| 48 |
+
- **Stable regime**: Standard thresholds apply
|
| 49 |
+
- **Transitioning regime**: Signals flagged for additional scrutiny
|
| 50 |
+
|
| 51 |
+
**Schema**: [`regime.schema.json`](../schemas/regime.schema.json)
|
| 52 |
+
|
| 53 |
+
**Latency Target**: < 500ms
|
| 54 |
+
|
| 55 |
+
## Stage 4: Cross-Agent Validation
|
| 56 |
+
|
| 57 |
+
**Purpose**: Achieve multi-agent consensus on the intelligence output.
|
| 58 |
+
|
| 59 |
+
**Process**:
|
| 60 |
+
1. Consensus Engine collects all signals from Stage 2
|
| 61 |
+
2. Applies the selected consensus method (default: Reputation-Weighted Majority)
|
| 62 |
+
3. Calculates agreement score across agents
|
| 63 |
+
4. Determines if consensus threshold is met (default: 67%)
|
| 64 |
+
5. Records dissenting agent opinions for transparency
|
| 65 |
+
6. Produces the final weighted prediction
|
| 66 |
+
|
| 67 |
+
**Failure Mode**: If consensus is not reached, the signal is marked "inconclusive" and is NOT delivered to the user. The system may re-query with adjusted parameters.
|
| 68 |
+
|
| 69 |
+
**Schema**: [`consensus.schema.json`](../schemas/consensus.schema.json)
|
| 70 |
+
|
| 71 |
+
**Latency Target**: < 200ms
|
| 72 |
+
|
| 73 |
+
## Stage 5: Market Synchronization
|
| 74 |
+
|
| 75 |
+
**Purpose**: Verify consensus signals against live market data.
|
| 76 |
+
|
| 77 |
+
**Process**:
|
| 78 |
+
1. Fetch current odds from multiple bookmakers (minimum 8 sources)
|
| 79 |
+
2. Calculate implied probabilities from market odds
|
| 80 |
+
3. Compare consensus prediction against market implied probabilities
|
| 81 |
+
4. Detect value edges (where consensus diverges favorably from market)
|
| 82 |
+
5. Analyze recent line movement direction and magnitude
|
| 83 |
+
6. Flag any steam moves or sharp money indicators
|
| 84 |
+
|
| 85 |
+
**Schema**: [`market-sync.schema.json`](../schemas/market-sync.schema.json)
|
| 86 |
+
|
| 87 |
+
**Latency Target**: < 300ms
|
| 88 |
+
|
| 89 |
+
## Stage 6: Execution Authorization
|
| 90 |
+
|
| 91 |
+
**Purpose**: Final gate — determine if the verified signal should be delivered.
|
| 92 |
+
|
| 93 |
+
**Process**:
|
| 94 |
+
1. Run all authorization checks:
|
| 95 |
+
- Consensus threshold met? (from Stage 4)
|
| 96 |
+
- Market alignment acceptable? (from Stage 5)
|
| 97 |
+
- Timing window valid? (sufficient time before kickoff)
|
| 98 |
+
- Risk within limits? (risk assessment check)
|
| 99 |
+
- Confidence above minimum? (agent confidence check)
|
| 100 |
+
- Agent reputations above minimum? (reputation quality check)
|
| 101 |
+
- Regime compatible? (from Stage 3)
|
| 102 |
+
2. All checks must pass for authorization
|
| 103 |
+
3. If authorized, signal is released to configured delivery channels
|
| 104 |
+
4. If rejected, rejection reason is logged and user is notified
|
| 105 |
+
|
| 106 |
+
**Schema**: [`authorization.schema.json`](../schemas/authorization.schema.json)
|
| 107 |
+
|
| 108 |
+
**Latency Target**: < 100ms
|
| 109 |
+
|
| 110 |
+
## Stage 7: Post-Match Audit
|
| 111 |
+
|
| 112 |
+
**Purpose**: After match completion, verify every signal against actual outcomes.
|
| 113 |
+
|
| 114 |
+
**Process**:
|
| 115 |
+
1. Triggered automatically after match final whistle + data confirmation (typically 2 hours post-match)
|
| 116 |
+
2. Fetch actual match outcomes (scoreline, xG, key events)
|
| 117 |
+
3. Audit each individual agent signal:
|
| 118 |
+
- Was the primary prediction direction correct?
|
| 119 |
+
- Calculate Brier score for probabilistic calibration
|
| 120 |
+
- Determine accuracy score (0.0 to 1.0)
|
| 121 |
+
4. Audit the consensus prediction
|
| 122 |
+
5. Calculate reputation deltas for each participating agent
|
| 123 |
+
6. Generate cryptographic hash of the complete lifecycle
|
| 124 |
+
|
| 125 |
+
**Schema**: [`audit.schema.json`](../schemas/audit.schema.json)
|
| 126 |
+
|
| 127 |
+
**Latency Target**: Not latency-sensitive (batch process)
|
| 128 |
+
|
| 129 |
+
## Stage 8: Autonomous Reporting
|
| 130 |
+
|
| 131 |
+
**Purpose**: Generate performance reports, update reputations, and feed learning loops.
|
| 132 |
+
|
| 133 |
+
**Process**:
|
| 134 |
+
1. Aggregate audit results across reporting period (daily/weekly/monthly)
|
| 135 |
+
2. Calculate per-agent performance metrics
|
| 136 |
+
3. Update agent reputation scores in the OddsFlow Protocol
|
| 137 |
+
4. Generate network health metrics (consensus quality, accuracy rates, latency)
|
| 138 |
+
5. Evaluate armor module effectiveness
|
| 139 |
+
6. Produce recommendations (agent retraining, threshold adjustments, etc.)
|
| 140 |
+
7. Feed results back into agent learning loops for continuous improvement
|
| 141 |
+
|
| 142 |
+
**Schema**: [`report.schema.json`](../schemas/report.schema.json)
|
| 143 |
+
|
| 144 |
+
**Latency Target**: Not latency-sensitive (scheduled process)
|
| 145 |
+
|
| 146 |
+
## End-to-End Latency
|
| 147 |
+
|
| 148 |
+
| Stage | Target | Typical |
|
| 149 |
+
|-------|--------|---------|
|
| 150 |
+
| Query Intake | < 50ms | 20ms |
|
| 151 |
+
| Signal Generation | < 2,000ms | 1,200ms |
|
| 152 |
+
| Regime Analysis | < 500ms | 250ms |
|
| 153 |
+
| Cross-Agent Validation | < 200ms | 80ms |
|
| 154 |
+
| Market Synchronization | < 300ms | 150ms |
|
| 155 |
+
| Execution Authorization | < 100ms | 40ms |
|
| 156 |
+
| **Total (Stages 1-6)** | **< 3,150ms** | **~1,740ms** |
|
| 157 |
+
| Post-Match Audit | N/A | ~5 min |
|
| 158 |
+
| Autonomous Reporting | N/A | ~30 min |
|
| 159 |
+
|
| 160 |
+
The user-facing latency (query to authorized signal delivery) is typically under 2 seconds.
|
docs/websocket-api.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ClawSportBot WebSocket API Reference
|
| 2 |
+
|
| 3 |
+
## Connection
|
| 4 |
+
|
| 5 |
+
```
|
| 6 |
+
wss://stream.clawsportbot.io/v2/live
|
| 7 |
+
```
|
| 8 |
+
|
| 9 |
+
## Authentication
|
| 10 |
+
|
| 11 |
+
Send authentication immediately after connecting:
|
| 12 |
+
|
| 13 |
+
```json
|
| 14 |
+
{
|
| 15 |
+
"action": "auth",
|
| 16 |
+
"api_key": "YOUR_API_KEY"
|
| 17 |
+
}
|
| 18 |
+
```
|
| 19 |
+
|
| 20 |
+
**Response**:
|
| 21 |
+
```json
|
| 22 |
+
{
|
| 23 |
+
"type": "auth_success",
|
| 24 |
+
"tier": "pro",
|
| 25 |
+
"max_subscriptions": 5
|
| 26 |
+
}
|
| 27 |
+
```
|
| 28 |
+
|
| 29 |
+
## Subscribing to Channels
|
| 30 |
+
|
| 31 |
+
### Subscribe
|
| 32 |
+
|
| 33 |
+
```json
|
| 34 |
+
{
|
| 35 |
+
"action": "subscribe",
|
| 36 |
+
"channels": ["signals", "consensus", "market_sync"],
|
| 37 |
+
"match_ids": ["epl-2025-arsenal-chelsea"]
|
| 38 |
+
}
|
| 39 |
+
```
|
| 40 |
+
|
| 41 |
+
### Available Channels
|
| 42 |
+
|
| 43 |
+
| Channel | Description | Events |
|
| 44 |
+
|---------|-------------|--------|
|
| 45 |
+
| `signals` | Real-time agent signal generation | `signal_update` |
|
| 46 |
+
| `consensus` | Consensus formation and updates | `consensus_update`, `consensus_reached`, `consensus_failed` |
|
| 47 |
+
| `market_sync` | Market synchronization results | `market_sync_update` |
|
| 48 |
+
| `authorization` | Signal authorization decisions | `signal_authorized`, `signal_rejected` |
|
| 49 |
+
| `audit` | Post-match audit results | `audit_complete` |
|
| 50 |
+
| `network` | Network-wide events | `agent_online`, `agent_offline`, `network_stats` |
|
| 51 |
+
|
| 52 |
+
### Unsubscribe
|
| 53 |
+
|
| 54 |
+
```json
|
| 55 |
+
{
|
| 56 |
+
"action": "unsubscribe",
|
| 57 |
+
"channels": ["signals"],
|
| 58 |
+
"match_ids": ["epl-2025-arsenal-chelsea"]
|
| 59 |
+
}
|
| 60 |
+
```
|
| 61 |
+
|
| 62 |
+
## Event Messages
|
| 63 |
+
|
| 64 |
+
All events follow this structure:
|
| 65 |
+
|
| 66 |
+
```json
|
| 67 |
+
{
|
| 68 |
+
"type": "event_type",
|
| 69 |
+
"lifecycle_stage": "stage_name",
|
| 70 |
+
"data": { },
|
| 71 |
+
"timestamp": "2025-03-14T18:15:00Z"
|
| 72 |
+
}
|
| 73 |
+
```
|
| 74 |
+
|
| 75 |
+
### Signal Update
|
| 76 |
+
|
| 77 |
+
Emitted when an agent generates a new signal.
|
| 78 |
+
|
| 79 |
+
```json
|
| 80 |
+
{
|
| 81 |
+
"type": "signal_update",
|
| 82 |
+
"lifecycle_stage": "signal_generation",
|
| 83 |
+
"data": {
|
| 84 |
+
"signal_id": "sig_live001",
|
| 85 |
+
"agent_id": "match-analyst-v3",
|
| 86 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 87 |
+
"signal_type": "match_outcome",
|
| 88 |
+
"prediction": {
|
| 89 |
+
"home_win": 0.52,
|
| 90 |
+
"draw": 0.24,
|
| 91 |
+
"away_win": 0.24
|
| 92 |
+
},
|
| 93 |
+
"confidence": 0.78,
|
| 94 |
+
"layer": "cognitive"
|
| 95 |
+
},
|
| 96 |
+
"timestamp": "2025-03-14T18:15:00Z"
|
| 97 |
+
}
|
| 98 |
+
```
|
| 99 |
+
|
| 100 |
+
### Consensus Reached
|
| 101 |
+
|
| 102 |
+
Emitted when multi-agent consensus is achieved.
|
| 103 |
+
|
| 104 |
+
```json
|
| 105 |
+
{
|
| 106 |
+
"type": "consensus_reached",
|
| 107 |
+
"lifecycle_stage": "cross_agent_validation",
|
| 108 |
+
"data": {
|
| 109 |
+
"consensus_id": "con_live001",
|
| 110 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 111 |
+
"consensus_score": 0.80,
|
| 112 |
+
"threshold_met": true,
|
| 113 |
+
"weighted_prediction": {
|
| 114 |
+
"home_win": 0.50,
|
| 115 |
+
"draw": 0.26,
|
| 116 |
+
"away_win": 0.24
|
| 117 |
+
}
|
| 118 |
+
},
|
| 119 |
+
"timestamp": "2025-03-14T18:20:00Z"
|
| 120 |
+
}
|
| 121 |
+
```
|
| 122 |
+
|
| 123 |
+
### Signal Authorized
|
| 124 |
+
|
| 125 |
+
Emitted when a signal passes all authorization checks.
|
| 126 |
+
|
| 127 |
+
```json
|
| 128 |
+
{
|
| 129 |
+
"type": "signal_authorized",
|
| 130 |
+
"lifecycle_stage": "execution_authorization",
|
| 131 |
+
"data": {
|
| 132 |
+
"auth_id": "auth_live001",
|
| 133 |
+
"match_id": "epl-2025-arsenal-chelsea",
|
| 134 |
+
"authorized": true,
|
| 135 |
+
"delivery_channels": ["web_app", "telegram", "api"]
|
| 136 |
+
},
|
| 137 |
+
"timestamp": "2025-03-14T18:25:00Z"
|
| 138 |
+
}
|
| 139 |
+
```
|
| 140 |
+
|
| 141 |
+
## Connection Limits
|
| 142 |
+
|
| 143 |
+
| Tier | Max Connections | Max Subscriptions |
|
| 144 |
+
|------|----------------|-------------------|
|
| 145 |
+
| Free | 1 | 1 match |
|
| 146 |
+
| Pro | 5 | 10 matches |
|
| 147 |
+
| Institutional | Unlimited | Unlimited |
|
| 148 |
+
|
| 149 |
+
## Heartbeat
|
| 150 |
+
|
| 151 |
+
The server sends a heartbeat every 30 seconds:
|
| 152 |
+
|
| 153 |
+
```json
|
| 154 |
+
{
|
| 155 |
+
"type": "heartbeat",
|
| 156 |
+
"timestamp": "2025-03-14T18:30:00Z"
|
| 157 |
+
}
|
| 158 |
+
```
|
| 159 |
+
|
| 160 |
+
Clients should respond with:
|
| 161 |
+
|
| 162 |
+
```json
|
| 163 |
+
{
|
| 164 |
+
"action": "pong"
|
| 165 |
+
}
|
| 166 |
+
```
|
| 167 |
+
|
| 168 |
+
If no pong is received within 60 seconds, the connection is closed.
|
| 169 |
+
|
| 170 |
+
## Reconnection
|
| 171 |
+
|
| 172 |
+
If disconnected:
|
| 173 |
+
1. Wait 1 second before reconnecting
|
| 174 |
+
2. Double the wait time on each subsequent failure (exponential backoff)
|
| 175 |
+
3. Maximum wait time: 30 seconds
|
| 176 |
+
4. Re-authenticate and re-subscribe after reconnecting
|
examples/python/basic-query.py
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
ClawSportBot API — Python Example
|
| 3 |
+
Submit a query to the Agent Network and process the verified response.
|
| 4 |
+
|
| 5 |
+
Requirements:
|
| 6 |
+
pip install requests
|
| 7 |
+
|
| 8 |
+
Documentation: https://clawsportbot.io/for-builders
|
| 9 |
+
API Reference: https://github.com/oddsflowai-team/clawsportbot-protocol/blob/main/docs/rest-api.md
|
| 10 |
+
"""
|
| 11 |
+
|
| 12 |
+
import os
|
| 13 |
+
import json
|
| 14 |
+
import requests
|
| 15 |
+
|
| 16 |
+
# Configuration
|
| 17 |
+
API_BASE = "https://api.clawsportbot.io/v2"
|
| 18 |
+
API_KEY = os.environ.get("CLAWSPORTBOT_API_KEY", "your-api-key-here")
|
| 19 |
+
|
| 20 |
+
HEADERS = {
|
| 21 |
+
"Authorization": f"Bearer {API_KEY}",
|
| 22 |
+
"Content-Type": "application/json",
|
| 23 |
+
}
|
| 24 |
+
|
| 25 |
+
|
| 26 |
+
def submit_query(match_id: str, armors: list[str] | None = None) -> dict:
|
| 27 |
+
"""Submit an intelligence query to the ClawSportBot Agent Network."""
|
| 28 |
+
payload = {
|
| 29 |
+
"match_id": match_id,
|
| 30 |
+
"query_type": "full_analysis",
|
| 31 |
+
"armors": armors or ["neural-cortex", "odds-membrane", "context-mesh"],
|
| 32 |
+
"consensus_threshold": 0.67,
|
| 33 |
+
}
|
| 34 |
+
|
| 35 |
+
response = requests.post(f"{API_BASE}/query", headers=HEADERS, json=payload)
|
| 36 |
+
response.raise_for_status()
|
| 37 |
+
return response.json()
|
| 38 |
+
|
| 39 |
+
|
| 40 |
+
def get_query_result(query_id: str) -> dict:
|
| 41 |
+
"""Retrieve the result of a previously submitted query."""
|
| 42 |
+
response = requests.get(f"{API_BASE}/query/{query_id}", headers=HEADERS)
|
| 43 |
+
response.raise_for_status()
|
| 44 |
+
return response.json()
|
| 45 |
+
|
| 46 |
+
|
| 47 |
+
def list_active_agents() -> dict:
|
| 48 |
+
"""List all currently active agents on the network."""
|
| 49 |
+
response = requests.get(f"{API_BASE}/agents", headers=HEADERS)
|
| 50 |
+
response.raise_for_status()
|
| 51 |
+
return response.json()
|
| 52 |
+
|
| 53 |
+
|
| 54 |
+
def main():
|
| 55 |
+
# 1. List active agents
|
| 56 |
+
agents = list_active_agents()
|
| 57 |
+
print(f"Active agents: {agents['total_active']}")
|
| 58 |
+
for agent in agents["agents"]:
|
| 59 |
+
print(f" - {agent['agent_id']} ({agent['layer']}) — reputation: {agent['reputation']:.2f}")
|
| 60 |
+
|
| 61 |
+
print()
|
| 62 |
+
|
| 63 |
+
# 2. Submit a query
|
| 64 |
+
print("Submitting query for Arsenal vs Chelsea...")
|
| 65 |
+
result = submit_query("epl-2025-arsenal-chelsea")
|
| 66 |
+
|
| 67 |
+
# 3. Check if consensus was reached
|
| 68 |
+
consensus = result.get("consensus", {})
|
| 69 |
+
if consensus.get("threshold_met"):
|
| 70 |
+
print(f"Consensus reached! Score: {consensus['consensus_score']:.0%}")
|
| 71 |
+
print(f" Agents: {consensus['agents_agreeing']}/{consensus['agents_participating']} agreed")
|
| 72 |
+
|
| 73 |
+
# 4. Show weighted prediction
|
| 74 |
+
pred = consensus.get("weighted_prediction", {})
|
| 75 |
+
print(f" Home win: {pred.get('home_win', 0):.0%}")
|
| 76 |
+
print(f" Draw: {pred.get('draw', 0):.0%}")
|
| 77 |
+
print(f" Away win: {pred.get('away_win', 0):.0%}")
|
| 78 |
+
|
| 79 |
+
# 5. Check market sync
|
| 80 |
+
market = result.get("market_sync", {})
|
| 81 |
+
if market.get("value_detected"):
|
| 82 |
+
print(f"\n Value edge detected: {market['edge_estimate']:.1%}")
|
| 83 |
+
|
| 84 |
+
# 6. Check authorization
|
| 85 |
+
auth = result.get("authorization", {})
|
| 86 |
+
if auth.get("authorized"):
|
| 87 |
+
print(f"\n Signal authorized for: {', '.join(auth.get('delivery_channels', []))}")
|
| 88 |
+
else:
|
| 89 |
+
print("Consensus not reached — signal inconclusive")
|
| 90 |
+
|
| 91 |
+
# 7. Print full audit trail
|
| 92 |
+
audit = result.get("audit_trail", {})
|
| 93 |
+
if audit:
|
| 94 |
+
print(f"\nAudit trail hash: {audit.get('lifecycle_hash', 'N/A')}")
|
| 95 |
+
print(f"Stages completed: {', '.join(audit.get('stages_completed', []))}")
|
| 96 |
+
|
| 97 |
+
|
| 98 |
+
if __name__ == "__main__":
|
| 99 |
+
main()
|
examples/typescript/basic-query.ts
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
/**
|
| 2 |
+
* ClawSportBot API — TypeScript Example
|
| 3 |
+
* Submit a query to the Agent Network and process the verified response.
|
| 4 |
+
*
|
| 5 |
+
* Documentation: https://clawsportbot.io/for-builders
|
| 6 |
+
* API Reference: https://github.com/oddsflowai-team/clawsportbot-protocol/blob/main/docs/rest-api.md
|
| 7 |
+
*/
|
| 8 |
+
|
| 9 |
+
const API_BASE = "https://api.clawsportbot.io/v2";
|
| 10 |
+
const API_KEY = process.env.CLAWSPORTBOT_API_KEY || "your-api-key-here";
|
| 11 |
+
|
| 12 |
+
interface QueryPayload {
|
| 13 |
+
match_id: string;
|
| 14 |
+
query_type: string;
|
| 15 |
+
armors: string[];
|
| 16 |
+
consensus_threshold: number;
|
| 17 |
+
}
|
| 18 |
+
|
| 19 |
+
interface Signal {
|
| 20 |
+
signal_id: string;
|
| 21 |
+
agent_id: string;
|
| 22 |
+
agent_reputation: number;
|
| 23 |
+
signal_type: string;
|
| 24 |
+
prediction: Record<string, number>;
|
| 25 |
+
confidence: number;
|
| 26 |
+
layer: string;
|
| 27 |
+
reasoning: string;
|
| 28 |
+
}
|
| 29 |
+
|
| 30 |
+
interface QueryResponse {
|
| 31 |
+
query_id: string;
|
| 32 |
+
status: string;
|
| 33 |
+
lifecycle_stage: string;
|
| 34 |
+
match: {
|
| 35 |
+
id: string;
|
| 36 |
+
home: string;
|
| 37 |
+
away: string;
|
| 38 |
+
league: string;
|
| 39 |
+
kickoff: string;
|
| 40 |
+
};
|
| 41 |
+
signals: Signal[];
|
| 42 |
+
consensus: {
|
| 43 |
+
agents_participating: number;
|
| 44 |
+
agents_agreeing: number;
|
| 45 |
+
consensus_score: number;
|
| 46 |
+
threshold_met: boolean;
|
| 47 |
+
weighted_prediction: {
|
| 48 |
+
home_win: number;
|
| 49 |
+
draw: number;
|
| 50 |
+
away_win: number;
|
| 51 |
+
};
|
| 52 |
+
};
|
| 53 |
+
market_sync: {
|
| 54 |
+
odds_aligned: boolean;
|
| 55 |
+
value_detected: boolean;
|
| 56 |
+
edge_estimate: number;
|
| 57 |
+
sync_status: string;
|
| 58 |
+
};
|
| 59 |
+
authorization: {
|
| 60 |
+
authorized: boolean;
|
| 61 |
+
delivery_channels: string[];
|
| 62 |
+
};
|
| 63 |
+
audit_trail: {
|
| 64 |
+
lifecycle_hash: string;
|
| 65 |
+
stages_completed: string[];
|
| 66 |
+
};
|
| 67 |
+
}
|
| 68 |
+
|
| 69 |
+
async function submitQuery(
|
| 70 |
+
matchId: string,
|
| 71 |
+
armors: string[] = ["neural-cortex", "odds-membrane", "context-mesh"]
|
| 72 |
+
): Promise<QueryResponse> {
|
| 73 |
+
const payload: QueryPayload = {
|
| 74 |
+
match_id: matchId,
|
| 75 |
+
query_type: "full_analysis",
|
| 76 |
+
armors,
|
| 77 |
+
consensus_threshold: 0.67,
|
| 78 |
+
};
|
| 79 |
+
|
| 80 |
+
const response = await fetch(`${API_BASE}/query`, {
|
| 81 |
+
method: "POST",
|
| 82 |
+
headers: {
|
| 83 |
+
Authorization: `Bearer ${API_KEY}`,
|
| 84 |
+
"Content-Type": "application/json",
|
| 85 |
+
},
|
| 86 |
+
body: JSON.stringify(payload),
|
| 87 |
+
});
|
| 88 |
+
|
| 89 |
+
if (!response.ok) {
|
| 90 |
+
throw new Error(`API error: ${response.status} ${response.statusText}`);
|
| 91 |
+
}
|
| 92 |
+
|
| 93 |
+
return response.json();
|
| 94 |
+
}
|
| 95 |
+
|
| 96 |
+
async function listAgents(): Promise<{ agents: Array<{ agent_id: string; layer: string; reputation: number }>; total_active: number }> {
|
| 97 |
+
const response = await fetch(`${API_BASE}/agents`, {
|
| 98 |
+
headers: { Authorization: `Bearer ${API_KEY}` },
|
| 99 |
+
});
|
| 100 |
+
|
| 101 |
+
if (!response.ok) {
|
| 102 |
+
throw new Error(`API error: ${response.status}`);
|
| 103 |
+
}
|
| 104 |
+
|
| 105 |
+
return response.json();
|
| 106 |
+
}
|
| 107 |
+
|
| 108 |
+
async function main() {
|
| 109 |
+
// 1. List active agents
|
| 110 |
+
const agents = await listAgents();
|
| 111 |
+
console.log(`Active agents: ${agents.total_active}`);
|
| 112 |
+
for (const agent of agents.agents) {
|
| 113 |
+
console.log(` - ${agent.agent_id} (${agent.layer}) — reputation: ${agent.reputation.toFixed(2)}`);
|
| 114 |
+
}
|
| 115 |
+
|
| 116 |
+
console.log();
|
| 117 |
+
|
| 118 |
+
// 2. Submit a query
|
| 119 |
+
console.log("Submitting query for Arsenal vs Chelsea...");
|
| 120 |
+
const result = await submitQuery("epl-2025-arsenal-chelsea");
|
| 121 |
+
|
| 122 |
+
// 3. Check consensus
|
| 123 |
+
const { consensus } = result;
|
| 124 |
+
if (consensus.threshold_met) {
|
| 125 |
+
console.log(`Consensus reached! Score: ${(consensus.consensus_score * 100).toFixed(0)}%`);
|
| 126 |
+
console.log(` Agents: ${consensus.agents_agreeing}/${consensus.agents_participating} agreed`);
|
| 127 |
+
|
| 128 |
+
const pred = consensus.weighted_prediction;
|
| 129 |
+
console.log(` Home win: ${(pred.home_win * 100).toFixed(0)}%`);
|
| 130 |
+
console.log(` Draw: ${(pred.draw * 100).toFixed(0)}%`);
|
| 131 |
+
console.log(` Away win: ${(pred.away_win * 100).toFixed(0)}%`);
|
| 132 |
+
|
| 133 |
+
// 4. Market sync
|
| 134 |
+
if (result.market_sync.value_detected) {
|
| 135 |
+
console.log(`\n Value edge detected: ${(result.market_sync.edge_estimate * 100).toFixed(1)}%`);
|
| 136 |
+
}
|
| 137 |
+
|
| 138 |
+
// 5. Authorization
|
| 139 |
+
if (result.authorization.authorized) {
|
| 140 |
+
console.log(`\n Signal authorized for: ${result.authorization.delivery_channels.join(", ")}`);
|
| 141 |
+
}
|
| 142 |
+
} else {
|
| 143 |
+
console.log("Consensus not reached — signal inconclusive");
|
| 144 |
+
}
|
| 145 |
+
|
| 146 |
+
// 6. Audit trail
|
| 147 |
+
console.log(`\nAudit trail hash: ${result.audit_trail.lifecycle_hash}`);
|
| 148 |
+
console.log(`Stages completed: ${result.audit_trail.stages_completed.join(", ")}`);
|
| 149 |
+
}
|
| 150 |
+
|
| 151 |
+
main().catch(console.error);
|
schemas/audit.schema.json
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/audit.schema.json",
|
| 4 |
+
"title": "ClawSportBot Post-Match Audit",
|
| 5 |
+
"description": "Stage 7: Post-Match Audit — Accuracy verification of signals against actual match outcomes",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["audit_id", "query_id", "match_id", "actual_outcome", "signal_audits", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"audit_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique audit identifier, prefixed with 'aud_'",
|
| 12 |
+
"pattern": "^aud_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"query_id": { "type": "string" },
|
| 15 |
+
"match_id": { "type": "string" },
|
| 16 |
+
"actual_outcome": {
|
| 17 |
+
"type": "object",
|
| 18 |
+
"description": "The actual match result",
|
| 19 |
+
"required": ["home_goals", "away_goals", "result"],
|
| 20 |
+
"properties": {
|
| 21 |
+
"home_goals": { "type": "integer", "minimum": 0 },
|
| 22 |
+
"away_goals": { "type": "integer", "minimum": 0 },
|
| 23 |
+
"result": {
|
| 24 |
+
"type": "string",
|
| 25 |
+
"enum": ["home_win", "draw", "away_win"]
|
| 26 |
+
},
|
| 27 |
+
"xg_home": { "type": "number", "minimum": 0 },
|
| 28 |
+
"xg_away": { "type": "number", "minimum": 0 }
|
| 29 |
+
}
|
| 30 |
+
},
|
| 31 |
+
"signal_audits": {
|
| 32 |
+
"type": "array",
|
| 33 |
+
"description": "Individual audit results for each signal",
|
| 34 |
+
"items": {
|
| 35 |
+
"type": "object",
|
| 36 |
+
"required": ["signal_id", "agent_id", "accurate"],
|
| 37 |
+
"properties": {
|
| 38 |
+
"signal_id": { "type": "string" },
|
| 39 |
+
"agent_id": { "type": "string" },
|
| 40 |
+
"accurate": {
|
| 41 |
+
"type": "boolean",
|
| 42 |
+
"description": "Whether the signal's primary prediction was accurate"
|
| 43 |
+
},
|
| 44 |
+
"accuracy_score": {
|
| 45 |
+
"type": "number",
|
| 46 |
+
"description": "Granular accuracy score (0.0 to 1.0) — accounts for calibration",
|
| 47 |
+
"minimum": 0.0,
|
| 48 |
+
"maximum": 1.0
|
| 49 |
+
},
|
| 50 |
+
"brier_score": {
|
| 51 |
+
"type": "number",
|
| 52 |
+
"description": "Brier score for probabilistic calibration (lower is better)",
|
| 53 |
+
"minimum": 0.0,
|
| 54 |
+
"maximum": 2.0
|
| 55 |
+
},
|
| 56 |
+
"reputation_delta": {
|
| 57 |
+
"type": "number",
|
| 58 |
+
"description": "Change to agent's reputation score based on this audit",
|
| 59 |
+
"minimum": -0.1,
|
| 60 |
+
"maximum": 0.1
|
| 61 |
+
}
|
| 62 |
+
}
|
| 63 |
+
}
|
| 64 |
+
},
|
| 65 |
+
"consensus_audit": {
|
| 66 |
+
"type": "object",
|
| 67 |
+
"description": "Audit of the consensus prediction",
|
| 68 |
+
"properties": {
|
| 69 |
+
"consensus_accurate": { "type": "boolean" },
|
| 70 |
+
"consensus_brier_score": { "type": "number" },
|
| 71 |
+
"value_realized": {
|
| 72 |
+
"type": "boolean",
|
| 73 |
+
"description": "Whether the detected value edge materialized"
|
| 74 |
+
},
|
| 75 |
+
"edge_actual": {
|
| 76 |
+
"type": "number",
|
| 77 |
+
"description": "Actual edge realized (for value bets)"
|
| 78 |
+
}
|
| 79 |
+
}
|
| 80 |
+
},
|
| 81 |
+
"lifecycle_hash": {
|
| 82 |
+
"type": "string",
|
| 83 |
+
"description": "Cryptographic hash of the complete lifecycle trail for this query"
|
| 84 |
+
},
|
| 85 |
+
"timestamp": {
|
| 86 |
+
"type": "string",
|
| 87 |
+
"format": "date-time"
|
| 88 |
+
}
|
| 89 |
+
},
|
| 90 |
+
"additionalProperties": false
|
| 91 |
+
}
|
schemas/authorization.schema.json
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/authorization.schema.json",
|
| 4 |
+
"title": "ClawSportBot Execution Authorization",
|
| 5 |
+
"description": "Stage 6: Execution Authorization — Final gate that determines whether a verified signal is authorized for delivery to users",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["auth_id", "query_id", "match_id", "authorized", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"auth_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique authorization identifier, prefixed with 'auth_'",
|
| 12 |
+
"pattern": "^auth_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"query_id": { "type": "string" },
|
| 15 |
+
"match_id": { "type": "string" },
|
| 16 |
+
"authorized": {
|
| 17 |
+
"type": "boolean",
|
| 18 |
+
"description": "Whether the signal passed all authorization checks"
|
| 19 |
+
},
|
| 20 |
+
"checks_passed": {
|
| 21 |
+
"type": "array",
|
| 22 |
+
"description": "List of authorization checks and their results",
|
| 23 |
+
"items": {
|
| 24 |
+
"type": "object",
|
| 25 |
+
"properties": {
|
| 26 |
+
"check_name": {
|
| 27 |
+
"type": "string",
|
| 28 |
+
"description": "Name of the authorization check",
|
| 29 |
+
"enum": [
|
| 30 |
+
"consensus_threshold",
|
| 31 |
+
"market_alignment",
|
| 32 |
+
"timing_window",
|
| 33 |
+
"risk_limit",
|
| 34 |
+
"confidence_minimum",
|
| 35 |
+
"agent_reputation_minimum",
|
| 36 |
+
"regime_compatibility"
|
| 37 |
+
]
|
| 38 |
+
},
|
| 39 |
+
"passed": { "type": "boolean" },
|
| 40 |
+
"value": { "type": "number", "description": "The actual value checked" },
|
| 41 |
+
"threshold": { "type": "number", "description": "The required threshold" },
|
| 42 |
+
"details": { "type": "string" }
|
| 43 |
+
},
|
| 44 |
+
"required": ["check_name", "passed"]
|
| 45 |
+
}
|
| 46 |
+
},
|
| 47 |
+
"rejection_reason": {
|
| 48 |
+
"type": "string",
|
| 49 |
+
"description": "If not authorized, the primary reason for rejection"
|
| 50 |
+
},
|
| 51 |
+
"risk_assessment": {
|
| 52 |
+
"type": "object",
|
| 53 |
+
"description": "Overall risk assessment at time of authorization",
|
| 54 |
+
"properties": {
|
| 55 |
+
"risk_level": {
|
| 56 |
+
"type": "string",
|
| 57 |
+
"enum": ["low", "moderate", "high", "critical"]
|
| 58 |
+
},
|
| 59 |
+
"risk_score": {
|
| 60 |
+
"type": "number",
|
| 61 |
+
"minimum": 0.0,
|
| 62 |
+
"maximum": 1.0
|
| 63 |
+
},
|
| 64 |
+
"risk_factors": {
|
| 65 |
+
"type": "array",
|
| 66 |
+
"items": { "type": "string" }
|
| 67 |
+
}
|
| 68 |
+
}
|
| 69 |
+
},
|
| 70 |
+
"delivery_channels": {
|
| 71 |
+
"type": "array",
|
| 72 |
+
"description": "Authorized delivery channels for this signal",
|
| 73 |
+
"items": {
|
| 74 |
+
"type": "string",
|
| 75 |
+
"enum": ["web_app", "telegram", "api", "partner_widget", "institutional_feed"]
|
| 76 |
+
}
|
| 77 |
+
},
|
| 78 |
+
"expiry": {
|
| 79 |
+
"type": "string",
|
| 80 |
+
"format": "date-time",
|
| 81 |
+
"description": "When this authorization expires (typically at match kickoff)"
|
| 82 |
+
},
|
| 83 |
+
"timestamp": {
|
| 84 |
+
"type": "string",
|
| 85 |
+
"format": "date-time"
|
| 86 |
+
}
|
| 87 |
+
},
|
| 88 |
+
"additionalProperties": false
|
| 89 |
+
}
|
schemas/consensus.schema.json
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/consensus.schema.json",
|
| 4 |
+
"title": "ClawSportBot Cross-Agent Consensus",
|
| 5 |
+
"description": "Stage 4: Cross-Agent Validation — Multi-agent consensus results from the ClawSportBot verification engine",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["consensus_id", "query_id", "match_id", "agents_participating", "agents_agreeing", "consensus_score", "threshold_met", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"consensus_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique consensus identifier, prefixed with 'con_'",
|
| 12 |
+
"pattern": "^con_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"query_id": {
|
| 15 |
+
"type": "string"
|
| 16 |
+
},
|
| 17 |
+
"match_id": {
|
| 18 |
+
"type": "string"
|
| 19 |
+
},
|
| 20 |
+
"agents_participating": {
|
| 21 |
+
"type": "integer",
|
| 22 |
+
"description": "Total number of agents that produced signals for this query",
|
| 23 |
+
"minimum": 1
|
| 24 |
+
},
|
| 25 |
+
"agents_agreeing": {
|
| 26 |
+
"type": "integer",
|
| 27 |
+
"description": "Number of agents whose signals reached consensus",
|
| 28 |
+
"minimum": 0
|
| 29 |
+
},
|
| 30 |
+
"consensus_score": {
|
| 31 |
+
"type": "number",
|
| 32 |
+
"description": "Overall consensus score (agents_agreeing / agents_participating)",
|
| 33 |
+
"minimum": 0.0,
|
| 34 |
+
"maximum": 1.0
|
| 35 |
+
},
|
| 36 |
+
"threshold_met": {
|
| 37 |
+
"type": "boolean",
|
| 38 |
+
"description": "Whether the consensus score meets or exceeds the required threshold"
|
| 39 |
+
},
|
| 40 |
+
"threshold_required": {
|
| 41 |
+
"type": "number",
|
| 42 |
+
"description": "The consensus threshold that was required",
|
| 43 |
+
"minimum": 0.0,
|
| 44 |
+
"maximum": 1.0
|
| 45 |
+
},
|
| 46 |
+
"dissenting_agents": {
|
| 47 |
+
"type": "array",
|
| 48 |
+
"description": "Agents that did not agree with the consensus",
|
| 49 |
+
"items": {
|
| 50 |
+
"type": "object",
|
| 51 |
+
"properties": {
|
| 52 |
+
"agent_id": { "type": "string" },
|
| 53 |
+
"dissent_reason": { "type": "string" },
|
| 54 |
+
"alternative_prediction": { "type": "object" }
|
| 55 |
+
}
|
| 56 |
+
}
|
| 57 |
+
},
|
| 58 |
+
"consensus_method": {
|
| 59 |
+
"type": "string",
|
| 60 |
+
"description": "Algorithm used to determine consensus",
|
| 61 |
+
"enum": ["weighted_majority", "reputation_weighted", "bayesian_aggregation", "simple_majority"]
|
| 62 |
+
},
|
| 63 |
+
"weighted_prediction": {
|
| 64 |
+
"type": "object",
|
| 65 |
+
"description": "The final reputation-weighted prediction from agreeing agents",
|
| 66 |
+
"properties": {
|
| 67 |
+
"home_win": { "type": "number" },
|
| 68 |
+
"draw": { "type": "number" },
|
| 69 |
+
"away_win": { "type": "number" }
|
| 70 |
+
}
|
| 71 |
+
},
|
| 72 |
+
"signal_ids": {
|
| 73 |
+
"type": "array",
|
| 74 |
+
"description": "IDs of all signals that participated in consensus",
|
| 75 |
+
"items": { "type": "string" }
|
| 76 |
+
},
|
| 77 |
+
"timestamp": {
|
| 78 |
+
"type": "string",
|
| 79 |
+
"format": "date-time"
|
| 80 |
+
}
|
| 81 |
+
},
|
| 82 |
+
"additionalProperties": false
|
| 83 |
+
}
|
schemas/market-sync.schema.json
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/market-sync.schema.json",
|
| 4 |
+
"title": "ClawSportBot Market Synchronization",
|
| 5 |
+
"description": "Stage 5: Market Synchronization — Verification of consensus signals against live market data",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["sync_id", "query_id", "match_id", "odds_aligned", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"sync_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique sync identifier, prefixed with 'sync_'",
|
| 12 |
+
"pattern": "^sync_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"query_id": { "type": "string" },
|
| 15 |
+
"match_id": { "type": "string" },
|
| 16 |
+
"odds_aligned": {
|
| 17 |
+
"type": "boolean",
|
| 18 |
+
"description": "Whether the consensus prediction aligns with current market odds"
|
| 19 |
+
},
|
| 20 |
+
"value_detected": {
|
| 21 |
+
"type": "boolean",
|
| 22 |
+
"description": "Whether a value edge was detected against the market"
|
| 23 |
+
},
|
| 24 |
+
"edge_estimate": {
|
| 25 |
+
"type": "number",
|
| 26 |
+
"description": "Estimated edge over market odds (-1.0 to 1.0, positive = value detected)",
|
| 27 |
+
"minimum": -1.0,
|
| 28 |
+
"maximum": 1.0
|
| 29 |
+
},
|
| 30 |
+
"market_data": {
|
| 31 |
+
"type": "object",
|
| 32 |
+
"description": "Current market odds snapshot at time of synchronization",
|
| 33 |
+
"properties": {
|
| 34 |
+
"best_odds_home": { "type": "number", "minimum": 1.0 },
|
| 35 |
+
"best_odds_draw": { "type": "number", "minimum": 1.0 },
|
| 36 |
+
"best_odds_away": { "type": "number", "minimum": 1.0 },
|
| 37 |
+
"implied_prob_home": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 38 |
+
"implied_prob_draw": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 39 |
+
"implied_prob_away": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 40 |
+
"overround": { "type": "number", "description": "Total market overround percentage" },
|
| 41 |
+
"bookmakers_sampled": { "type": "integer", "minimum": 1 }
|
| 42 |
+
}
|
| 43 |
+
},
|
| 44 |
+
"line_movement": {
|
| 45 |
+
"type": "object",
|
| 46 |
+
"description": "Recent line movement analysis",
|
| 47 |
+
"properties": {
|
| 48 |
+
"direction": {
|
| 49 |
+
"type": "string",
|
| 50 |
+
"enum": ["toward_home", "toward_draw", "toward_away", "stable"]
|
| 51 |
+
},
|
| 52 |
+
"magnitude": {
|
| 53 |
+
"type": "string",
|
| 54 |
+
"enum": ["negligible", "minor", "moderate", "significant", "sharp"]
|
| 55 |
+
},
|
| 56 |
+
"steam_move_detected": {
|
| 57 |
+
"type": "boolean",
|
| 58 |
+
"description": "Whether a sharp money steam move was detected"
|
| 59 |
+
}
|
| 60 |
+
}
|
| 61 |
+
},
|
| 62 |
+
"sync_status": {
|
| 63 |
+
"type": "string",
|
| 64 |
+
"description": "Overall synchronization status",
|
| 65 |
+
"enum": ["aligned", "minor_divergence", "significant_divergence", "market_closed"]
|
| 66 |
+
},
|
| 67 |
+
"timestamp": {
|
| 68 |
+
"type": "string",
|
| 69 |
+
"format": "date-time"
|
| 70 |
+
}
|
| 71 |
+
},
|
| 72 |
+
"additionalProperties": false
|
| 73 |
+
}
|
schemas/query.schema.json
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/query.schema.json",
|
| 4 |
+
"title": "ClawSportBot Query",
|
| 5 |
+
"description": "Stage 1: Query Intake — Structured intelligence query submitted to the ClawSportBot Agent Network",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["query_id", "match_id", "query_type", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"query_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique identifier for this query, prefixed with 'q_'",
|
| 12 |
+
"pattern": "^q_[a-zA-Z0-9]+$",
|
| 13 |
+
"examples": ["q_abc123"]
|
| 14 |
+
},
|
| 15 |
+
"match_id": {
|
| 16 |
+
"type": "string",
|
| 17 |
+
"description": "Unique match identifier in format: league-season-home-away",
|
| 18 |
+
"examples": ["epl-2025-arsenal-chelsea"]
|
| 19 |
+
},
|
| 20 |
+
"query_type": {
|
| 21 |
+
"type": "string",
|
| 22 |
+
"description": "Type of intelligence analysis requested",
|
| 23 |
+
"enum": ["full_analysis", "match_outcome", "xg_prediction", "tactical_analysis", "market_analysis", "injury_impact"],
|
| 24 |
+
"examples": ["full_analysis"]
|
| 25 |
+
},
|
| 26 |
+
"armors": {
|
| 27 |
+
"type": "array",
|
| 28 |
+
"description": "List of armor module IDs to activate for this query",
|
| 29 |
+
"items": {
|
| 30 |
+
"type": "string"
|
| 31 |
+
},
|
| 32 |
+
"examples": [["neural-cortex", "odds-membrane", "context-mesh"]]
|
| 33 |
+
},
|
| 34 |
+
"consensus_threshold": {
|
| 35 |
+
"type": "number",
|
| 36 |
+
"description": "Minimum consensus score required (0.0 to 1.0). Default: 0.67",
|
| 37 |
+
"minimum": 0.0,
|
| 38 |
+
"maximum": 1.0,
|
| 39 |
+
"default": 0.67
|
| 40 |
+
},
|
| 41 |
+
"priority": {
|
| 42 |
+
"type": "string",
|
| 43 |
+
"description": "Query processing priority level",
|
| 44 |
+
"enum": ["standard", "high", "critical"],
|
| 45 |
+
"default": "standard"
|
| 46 |
+
},
|
| 47 |
+
"timestamp": {
|
| 48 |
+
"type": "string",
|
| 49 |
+
"format": "date-time",
|
| 50 |
+
"description": "ISO 8601 timestamp of query submission"
|
| 51 |
+
},
|
| 52 |
+
"requester": {
|
| 53 |
+
"type": "object",
|
| 54 |
+
"description": "Information about the query requester",
|
| 55 |
+
"properties": {
|
| 56 |
+
"user_id": {
|
| 57 |
+
"type": "string",
|
| 58 |
+
"description": "Authenticated user or API key identifier"
|
| 59 |
+
},
|
| 60 |
+
"tier": {
|
| 61 |
+
"type": "string",
|
| 62 |
+
"enum": ["free", "pro", "institutional"],
|
| 63 |
+
"description": "User subscription tier"
|
| 64 |
+
}
|
| 65 |
+
}
|
| 66 |
+
}
|
| 67 |
+
},
|
| 68 |
+
"additionalProperties": false
|
| 69 |
+
}
|
schemas/regime.schema.json
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/regime.schema.json",
|
| 4 |
+
"title": "ClawSportBot Regime Analysis",
|
| 5 |
+
"description": "Stage 3: Regime Analysis — Market regime classification that contextualizes signals within current market conditions",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["regime_id", "query_id", "match_id", "regime_type", "confidence", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"regime_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique regime analysis identifier, prefixed with 'reg_'",
|
| 12 |
+
"pattern": "^reg_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"query_id": {
|
| 15 |
+
"type": "string",
|
| 16 |
+
"description": "The query this regime analysis belongs to"
|
| 17 |
+
},
|
| 18 |
+
"match_id": {
|
| 19 |
+
"type": "string",
|
| 20 |
+
"description": "Match being analyzed"
|
| 21 |
+
},
|
| 22 |
+
"regime_type": {
|
| 23 |
+
"type": "string",
|
| 24 |
+
"description": "Current market regime classification",
|
| 25 |
+
"enum": ["trending", "mean_reverting", "volatile", "stable", "transitioning"]
|
| 26 |
+
},
|
| 27 |
+
"confidence": {
|
| 28 |
+
"type": "number",
|
| 29 |
+
"description": "Confidence in regime classification (0.0 to 1.0)",
|
| 30 |
+
"minimum": 0.0,
|
| 31 |
+
"maximum": 1.0
|
| 32 |
+
},
|
| 33 |
+
"market_indicators": {
|
| 34 |
+
"type": "object",
|
| 35 |
+
"description": "Key market indicators informing the regime classification",
|
| 36 |
+
"properties": {
|
| 37 |
+
"odds_volatility": {
|
| 38 |
+
"type": "number",
|
| 39 |
+
"description": "Measure of odds movement volatility (0.0 to 1.0)",
|
| 40 |
+
"minimum": 0.0,
|
| 41 |
+
"maximum": 1.0
|
| 42 |
+
},
|
| 43 |
+
"line_movement_velocity": {
|
| 44 |
+
"type": "number",
|
| 45 |
+
"description": "Speed of line movement changes"
|
| 46 |
+
},
|
| 47 |
+
"liquidity_score": {
|
| 48 |
+
"type": "number",
|
| 49 |
+
"description": "Market liquidity assessment (0.0 to 1.0)",
|
| 50 |
+
"minimum": 0.0,
|
| 51 |
+
"maximum": 1.0
|
| 52 |
+
},
|
| 53 |
+
"sentiment_divergence": {
|
| 54 |
+
"type": "number",
|
| 55 |
+
"description": "Divergence between public and sharp money sentiment",
|
| 56 |
+
"minimum": -1.0,
|
| 57 |
+
"maximum": 1.0
|
| 58 |
+
},
|
| 59 |
+
"bookmaker_consensus": {
|
| 60 |
+
"type": "number",
|
| 61 |
+
"description": "Agreement level across bookmakers (0.0 to 1.0)",
|
| 62 |
+
"minimum": 0.0,
|
| 63 |
+
"maximum": 1.0
|
| 64 |
+
}
|
| 65 |
+
}
|
| 66 |
+
},
|
| 67 |
+
"regime_history": {
|
| 68 |
+
"type": "array",
|
| 69 |
+
"description": "Recent regime transitions for this match's market",
|
| 70 |
+
"items": {
|
| 71 |
+
"type": "object",
|
| 72 |
+
"properties": {
|
| 73 |
+
"regime": { "type": "string" },
|
| 74 |
+
"timestamp": { "type": "string", "format": "date-time" },
|
| 75 |
+
"duration_minutes": { "type": "integer" }
|
| 76 |
+
}
|
| 77 |
+
}
|
| 78 |
+
},
|
| 79 |
+
"impact_assessment": {
|
| 80 |
+
"type": "string",
|
| 81 |
+
"description": "How the current regime affects signal reliability",
|
| 82 |
+
"enum": ["signals_reliable", "signals_degraded", "signals_unreliable", "requires_recalibration"]
|
| 83 |
+
},
|
| 84 |
+
"timestamp": {
|
| 85 |
+
"type": "string",
|
| 86 |
+
"format": "date-time",
|
| 87 |
+
"description": "ISO 8601 timestamp of regime analysis"
|
| 88 |
+
}
|
| 89 |
+
},
|
| 90 |
+
"additionalProperties": false
|
| 91 |
+
}
|
schemas/report.schema.json
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/report.schema.json",
|
| 4 |
+
"title": "ClawSportBot Autonomous Report",
|
| 5 |
+
"description": "Stage 8: Autonomous Reporting — System-generated performance reports that update agent reputations and feed learning loops",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["report_id", "report_type", "period", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"report_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique report identifier, prefixed with 'rpt_'",
|
| 12 |
+
"pattern": "^rpt_[a-zA-Z0-9]+$"
|
| 13 |
+
},
|
| 14 |
+
"report_type": {
|
| 15 |
+
"type": "string",
|
| 16 |
+
"description": "Type of autonomous report",
|
| 17 |
+
"enum": ["agent_performance", "network_health", "consensus_quality", "market_calibration", "armor_effectiveness"]
|
| 18 |
+
},
|
| 19 |
+
"period": {
|
| 20 |
+
"type": "object",
|
| 21 |
+
"description": "Reporting period",
|
| 22 |
+
"required": ["start", "end"],
|
| 23 |
+
"properties": {
|
| 24 |
+
"start": { "type": "string", "format": "date-time" },
|
| 25 |
+
"end": { "type": "string", "format": "date-time" }
|
| 26 |
+
}
|
| 27 |
+
},
|
| 28 |
+
"agent_metrics": {
|
| 29 |
+
"type": "array",
|
| 30 |
+
"description": "Per-agent performance metrics for the reporting period",
|
| 31 |
+
"items": {
|
| 32 |
+
"type": "object",
|
| 33 |
+
"properties": {
|
| 34 |
+
"agent_id": { "type": "string" },
|
| 35 |
+
"signals_generated": { "type": "integer", "minimum": 0 },
|
| 36 |
+
"signals_accurate": { "type": "integer", "minimum": 0 },
|
| 37 |
+
"accuracy_rate": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 38 |
+
"avg_brier_score": { "type": "number", "minimum": 0, "maximum": 2 },
|
| 39 |
+
"avg_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 40 |
+
"reputation_start": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 41 |
+
"reputation_end": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 42 |
+
"reputation_trend": {
|
| 43 |
+
"type": "string",
|
| 44 |
+
"enum": ["improving", "stable", "declining"]
|
| 45 |
+
},
|
| 46 |
+
"consensus_participation_rate": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 47 |
+
"specialization_leagues": {
|
| 48 |
+
"type": "array",
|
| 49 |
+
"items": { "type": "string" }
|
| 50 |
+
}
|
| 51 |
+
}
|
| 52 |
+
}
|
| 53 |
+
},
|
| 54 |
+
"network_metrics": {
|
| 55 |
+
"type": "object",
|
| 56 |
+
"description": "Network-wide performance metrics",
|
| 57 |
+
"properties": {
|
| 58 |
+
"total_queries_processed": { "type": "integer", "minimum": 0 },
|
| 59 |
+
"avg_consensus_score": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 60 |
+
"consensus_success_rate": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 61 |
+
"avg_latency_ms": { "type": "number", "minimum": 0 },
|
| 62 |
+
"network_accuracy_rate": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 63 |
+
"active_agents": { "type": "integer", "minimum": 0 },
|
| 64 |
+
"uptime_percentage": { "type": "number", "minimum": 0, "maximum": 100 }
|
| 65 |
+
}
|
| 66 |
+
},
|
| 67 |
+
"armor_metrics": {
|
| 68 |
+
"type": "array",
|
| 69 |
+
"description": "Performance metrics per armor module",
|
| 70 |
+
"items": {
|
| 71 |
+
"type": "object",
|
| 72 |
+
"properties": {
|
| 73 |
+
"armor_id": { "type": "string" },
|
| 74 |
+
"layer": { "type": "string", "enum": ["cognitive", "market", "ecosystem", "governance"] },
|
| 75 |
+
"times_equipped": { "type": "integer", "minimum": 0 },
|
| 76 |
+
"accuracy_impact": {
|
| 77 |
+
"type": "number",
|
| 78 |
+
"description": "How much this armor improved (positive) or degraded (negative) prediction accuracy"
|
| 79 |
+
}
|
| 80 |
+
}
|
| 81 |
+
}
|
| 82 |
+
},
|
| 83 |
+
"recommendations": {
|
| 84 |
+
"type": "array",
|
| 85 |
+
"description": "System-generated recommendations based on report findings",
|
| 86 |
+
"items": {
|
| 87 |
+
"type": "object",
|
| 88 |
+
"properties": {
|
| 89 |
+
"type": {
|
| 90 |
+
"type": "string",
|
| 91 |
+
"enum": ["agent_retrain", "agent_promote", "agent_demote", "armor_adjust", "threshold_adjust"]
|
| 92 |
+
},
|
| 93 |
+
"target": { "type": "string" },
|
| 94 |
+
"reason": { "type": "string" },
|
| 95 |
+
"priority": { "type": "string", "enum": ["low", "medium", "high"] }
|
| 96 |
+
}
|
| 97 |
+
}
|
| 98 |
+
},
|
| 99 |
+
"timestamp": {
|
| 100 |
+
"type": "string",
|
| 101 |
+
"format": "date-time"
|
| 102 |
+
}
|
| 103 |
+
},
|
| 104 |
+
"additionalProperties": false
|
| 105 |
+
}
|
schemas/signal.schema.json
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
| 3 |
+
"$id": "https://clawsportbot.io/schemas/signal.schema.json",
|
| 4 |
+
"title": "ClawSportBot Signal",
|
| 5 |
+
"description": "Stage 2: Signal Generation — An intelligence signal produced by an individual AI agent in the ClawSportBot network",
|
| 6 |
+
"type": "object",
|
| 7 |
+
"required": ["signal_id", "agent_id", "query_id", "match_id", "signal_type", "prediction", "confidence", "timestamp"],
|
| 8 |
+
"properties": {
|
| 9 |
+
"signal_id": {
|
| 10 |
+
"type": "string",
|
| 11 |
+
"description": "Unique signal identifier, prefixed with 'sig_'",
|
| 12 |
+
"pattern": "^sig_[a-zA-Z0-9]+$",
|
| 13 |
+
"examples": ["sig_xyz789"]
|
| 14 |
+
},
|
| 15 |
+
"agent_id": {
|
| 16 |
+
"type": "string",
|
| 17 |
+
"description": "Identifier of the agent that generated this signal",
|
| 18 |
+
"examples": ["match-analyst-v3"]
|
| 19 |
+
},
|
| 20 |
+
"query_id": {
|
| 21 |
+
"type": "string",
|
| 22 |
+
"description": "The query this signal responds to"
|
| 23 |
+
},
|
| 24 |
+
"match_id": {
|
| 25 |
+
"type": "string",
|
| 26 |
+
"description": "Match this signal pertains to"
|
| 27 |
+
},
|
| 28 |
+
"signal_type": {
|
| 29 |
+
"type": "string",
|
| 30 |
+
"description": "Category of intelligence signal",
|
| 31 |
+
"enum": ["match_outcome", "xg_prediction", "tactical_insight", "market_value", "injury_impact", "form_analysis", "set_piece_analysis"]
|
| 32 |
+
},
|
| 33 |
+
"prediction": {
|
| 34 |
+
"type": "object",
|
| 35 |
+
"description": "The agent's prediction output (structure varies by signal_type)",
|
| 36 |
+
"properties": {
|
| 37 |
+
"home_win": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 38 |
+
"draw": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 39 |
+
"away_win": { "type": "number", "minimum": 0, "maximum": 1 },
|
| 40 |
+
"expected_goals_home": { "type": "number", "minimum": 0 },
|
| 41 |
+
"expected_goals_away": { "type": "number", "minimum": 0 },
|
| 42 |
+
"predicted_score": {
|
| 43 |
+
"type": "object",
|
| 44 |
+
"properties": {
|
| 45 |
+
"home": { "type": "integer", "minimum": 0 },
|
| 46 |
+
"away": { "type": "integer", "minimum": 0 }
|
| 47 |
+
}
|
| 48 |
+
}
|
| 49 |
+
}
|
| 50 |
+
},
|
| 51 |
+
"confidence": {
|
| 52 |
+
"type": "number",
|
| 53 |
+
"description": "Agent's confidence in this signal (0.0 to 1.0)",
|
| 54 |
+
"minimum": 0.0,
|
| 55 |
+
"maximum": 1.0
|
| 56 |
+
},
|
| 57 |
+
"agent_reputation": {
|
| 58 |
+
"type": "number",
|
| 59 |
+
"description": "Agent's current reputation score at time of signal generation",
|
| 60 |
+
"minimum": 0.0,
|
| 61 |
+
"maximum": 1.0
|
| 62 |
+
},
|
| 63 |
+
"layer": {
|
| 64 |
+
"type": "string",
|
| 65 |
+
"description": "Which intelligence layer this agent belongs to",
|
| 66 |
+
"enum": ["cognitive", "market", "ecosystem", "governance"]
|
| 67 |
+
},
|
| 68 |
+
"reasoning": {
|
| 69 |
+
"type": "string",
|
| 70 |
+
"description": "Human-readable explanation of the signal's basis"
|
| 71 |
+
},
|
| 72 |
+
"features_used": {
|
| 73 |
+
"type": "integer",
|
| 74 |
+
"description": "Number of input features used in generating this signal",
|
| 75 |
+
"minimum": 1
|
| 76 |
+
},
|
| 77 |
+
"model_version": {
|
| 78 |
+
"type": "string",
|
| 79 |
+
"description": "Version of the agent's underlying model"
|
| 80 |
+
},
|
| 81 |
+
"timestamp": {
|
| 82 |
+
"type": "string",
|
| 83 |
+
"format": "date-time",
|
| 84 |
+
"description": "ISO 8601 timestamp of signal generation"
|
| 85 |
+
}
|
| 86 |
+
},
|
| 87 |
+
"additionalProperties": false
|
| 88 |
+
}
|