docs(sdk): add comprehensive Janus SDK documentation
Add README.md with: - Architecture overview with diagram - Quick start examples (Identity, QVL, GQL) - Module reference for all public APIs - GQL syntax guide (MATCH, CREATE, DELETE, RETURN) - Design principles (Exit is Voice, Profit=Honesty, etc.) - Testing instructions - Sprint roadmap Covers Sprint 3: Documentation
This commit is contained in:
Markus Maiwald
parent
19577e99f8
commit
ff40f3739c
|
|
@ -2,81 +2,336 @@
|
|||
|
||||
> Sovereign; Kinetic; Anti-Fragile.
|
||||
|
||||
The Libertaria SDK provides primitives for building sovereign agent networks on top of Janus.
|
||||
**Version:** 0.2.0-alpha
|
||||
**Status:** Sprint 2 Complete (GQL Parser + Codegen)
|
||||
**License:** MIT + Libertaria Commons Clause
|
||||
|
||||
**Status:** v0.1.0-alpha (2026-02-03)
|
||||
---
|
||||
|
||||
## Core Modules
|
||||
## Overview
|
||||
|
||||
| Module | File | Status | Purpose |
|
||||
|--------|------|--------|---------|
|
||||
| `identity` | `identity.jan` | ✅ Draft | Cryptographic agent identity with rotation/burn |
|
||||
| `message` | `message.jan` | ✅ Draft | Signed, content-addressed messages |
|
||||
| `context` | `context.jan` | ✅ Draft | NCP (Nexus Context Protocol) implementation |
|
||||
| `memory` | `memory.jan` | ✅ Draft | Vector-backed semantic memory (LanceDB) |
|
||||
| `lib` | `lib.jan` | ✅ Draft | Unified API export |
|
||||
The Libertaria SDK provides primitives for building sovereign agent networks on top of [Janus](https://github.com/janus-lang/janus) — the programming language designed for Carbon-Silicon symbiosis.
|
||||
|
||||
## Quick Start
|
||||
This SDK implements the **L1 Identity Layer** of the Libertaria Stack, featuring:
|
||||
|
||||
```janus
|
||||
import libertaria
|
||||
- **Cryptographic Identity** — Ed25519-based with rotation and burn capabilities
|
||||
- **Trust Graph** — QVL (Quasar Vector Lattice) engine with betrayal detection
|
||||
- **GQL (Graph Query Language)** — ISO/IEC 39075:2024 compliant query interface
|
||||
- **Persistent Storage** — libmdbx backend with Kenya Rule compliance (<10MB)
|
||||
|
||||
-- Create sovereign agent
|
||||
let agent = libertaria.create_sovereign_agent()
|
||||
|
||||
-- Create identity with rotation capability
|
||||
let (new_id, old_id) = identity.rotate(agent.identity)
|
||||
|
||||
-- Send signed message
|
||||
let msg = message.create(
|
||||
from = agent.identity,
|
||||
content_type = Text,
|
||||
content = bytes.from_string("Hello Sovereigns!")
|
||||
)
|
||||
|
||||
-- Create hierarchical context
|
||||
let ctx = context.create({})
|
||||
let sub_ctx = context.fork(ctx, reason = "Sub-conversation")?
|
||||
|
||||
-- Store in semantic memory
|
||||
let emb = memory.embed(message.content(msg))
|
||||
let vs = memory.store(agent.memory, message.id(msg), emb, "...")
|
||||
```
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Exit is Voice** — Agents can leave, taking their data cryptographically (`identity.burn`)
|
||||
2. **Profit = Honesty** — Economic stakes align incentives (staking module planned)
|
||||
3. **Code is Law** — No central moderation, only protocol rules
|
||||
4. **Binary APIs** — gRPC/MsgPack/QUIC over REST
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (Your Agent / libertaria.bot) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Libertaria SDK │
|
||||
├──────────┬──────────┬──────────┬────────────┤
|
||||
│ Identity │ Message │ Context │ Memory │
|
||||
│ │ │ (NCP) │ (LanceDB) │
|
||||
├──────────┴──────────┴──────────┴────────────┤
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Identity │ │ Trust Graph │ │ GQL │ │
|
||||
│ │ (identity) │ │ (qvl) │ │ (gql/*.zig) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Message │ │ Context │ │ Memory │ │
|
||||
│ │ (message) │ │ (context) │ │ (memory) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Janus Standard Library │
|
||||
├─────────────────────────────────────────────┤
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Janus Compiler (:service) │
|
||||
└─────────────────────────────────────────────┘
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
---
|
||||
|
||||
- [ ] Staking/Economics module (spam prevention)
|
||||
- [ ] Channel module (QUIC transport)
|
||||
- [ ] Discovery module (DHT-based agent lookup)
|
||||
- [ ] Governance module (voting, proposals)
|
||||
- [ ] Test suite
|
||||
- [ ] Integration with Janus compiler
|
||||
## Quick Start
|
||||
|
||||
### 1. Sovereign Identity
|
||||
|
||||
```janus
|
||||
import libertaria.{identity}
|
||||
|
||||
// Create a new sovereign identity
|
||||
let id = identity.create()
|
||||
|
||||
// Sign a message
|
||||
let msg = bytes.from_string("Hello Sovereigns!")
|
||||
let sig = identity.sign(id, msg)
|
||||
|
||||
// Verify signature
|
||||
assert identity.verify(id, msg, sig)
|
||||
|
||||
// Rotate identity (new keys, linked provenance)
|
||||
let (new_id, old_id) = identity.rotate(id)
|
||||
|
||||
// Burn identity (cryptographic deletion)
|
||||
let burned = identity.burn(id)
|
||||
```
|
||||
|
||||
### 2. Trust Graph (QVL)
|
||||
|
||||
```janus
|
||||
import libertaria.{qvl}
|
||||
|
||||
// Create hybrid graph (persistent + in-memory)
|
||||
let graph = qvl.HybridGraph.init(&persistent, allocator)
|
||||
|
||||
// Add trust edges
|
||||
graph.addEdge(.{
|
||||
from = alice,
|
||||
to = bob,
|
||||
risk = -0.3, // Negative = trust
|
||||
level = 3, // Trust level 1-7
|
||||
timestamp = now(),
|
||||
expires_at = now() + duration.days(30)
|
||||
})
|
||||
|
||||
// Detect betrayal rings (negative cycles)
|
||||
let result = try graph.detectBetrayal(alice)
|
||||
if result.betrayal_cycles.items.len > 0 {
|
||||
// Handle betrayal
|
||||
}
|
||||
|
||||
// Find trust path
|
||||
let path = try graph.findTrustPath(alice, charlie,
|
||||
heuristic = qvl.reputationHeuristic,
|
||||
heuristic_ctx = &rep_map)
|
||||
```
|
||||
|
||||
### 3. GQL (Graph Query Language)
|
||||
|
||||
```janus
|
||||
import libertaria.{gql}
|
||||
|
||||
// Parse GQL query
|
||||
let query_str = "MATCH (n:Identity)-[t:TRUST]->(m) WHERE n.did = 'alice' RETURN m"
|
||||
let query = try gql.parse(allocator, query_str)
|
||||
defer query.deinit()
|
||||
|
||||
// Transpile to Zig code
|
||||
let zig_code = try gql.generateZig(allocator, query)
|
||||
defer allocator.free(zig_code)
|
||||
|
||||
// Generated code looks like:
|
||||
// pub fn execute(graph: *qvl.HybridGraph) !void {
|
||||
// // MATCH statement
|
||||
// // Traverse from n
|
||||
// var t = try graph.getOutgoing(n);
|
||||
// // Filter by type: TRUST
|
||||
// var m = t.to;
|
||||
// // WHERE n.did == "alice"
|
||||
// // RETURN statement
|
||||
// var results = std.ArrayList(Result).init(allocator);
|
||||
// defer results.deinit();
|
||||
// try results.append(m);
|
||||
// }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Reference
|
||||
|
||||
### `libertaria.identity`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `create()` | Generate new Ed25519 identity |
|
||||
| `rotate(id)` | Rotate keys with provenance chain |
|
||||
| `burn(id)` | Cryptographic deletion |
|
||||
| `sign(id, msg)` | Sign message |
|
||||
| `verify(id, msg, sig)` | Verify signature |
|
||||
| `is_valid(id)` | Check not revoked/expired |
|
||||
|
||||
### `libertaria.qvl`
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| `HybridGraph` | Persistent + in-memory graph |
|
||||
| `PersistentGraph` | libmdbx-backed storage |
|
||||
| `RiskGraph` | In-memory graph for algorithms |
|
||||
| `GraphTransaction` | Batch operations |
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `detectBetrayal(source)` | Bellman-Ford negative cycle detection |
|
||||
| `findTrustPath(src, tgt, heuristic)` | A* pathfinding |
|
||||
| `addEdge(edge)` | Add trust edge |
|
||||
| `getOutgoing(node)` | Get neighbors |
|
||||
|
||||
### `libertaria.gql`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `parse(allocator, query)` | Parse GQL string to AST |
|
||||
| `generateZig(allocator, query)` | Transpile to Zig code |
|
||||
|
||||
---
|
||||
|
||||
## GQL Syntax
|
||||
|
||||
### MATCH — Pattern Matching
|
||||
|
||||
```gql
|
||||
-- Simple node
|
||||
MATCH (n:Identity)
|
||||
|
||||
-- Node with properties
|
||||
MATCH (n:Identity {did: 'alice', active: true})
|
||||
|
||||
-- One-hop traversal
|
||||
MATCH (a)-[t:TRUST]->(b)
|
||||
|
||||
-- Variable-length path
|
||||
MATCH (a)-[t:TRUST*1..3]->(b)
|
||||
|
||||
-- With WHERE clause
|
||||
MATCH (n:Identity)-[t:TRUST]->(m)
|
||||
WHERE n.did = 'alice' AND t.level >= 3
|
||||
RETURN m
|
||||
```
|
||||
|
||||
### CREATE — Insert Data
|
||||
|
||||
```gql
|
||||
-- Create node
|
||||
CREATE (n:Identity {did: 'alice'})
|
||||
|
||||
-- Create edge
|
||||
CREATE (a)-[t:TRUST {level: 3}]->(b)
|
||||
|
||||
-- Create pattern
|
||||
CREATE (a:Identity)-[t:TRUST]->(b:Identity)
|
||||
```
|
||||
|
||||
### DELETE — Remove Data
|
||||
|
||||
```gql
|
||||
-- Delete nodes
|
||||
MATCH (n:Identity)
|
||||
WHERE n.did = 'compromised'
|
||||
DELETE n
|
||||
```
|
||||
|
||||
### RETURN — Project Results
|
||||
|
||||
```gql
|
||||
-- Return variable
|
||||
MATCH (n) RETURN n
|
||||
|
||||
-- Return multiple
|
||||
MATCH (a)-[t]->(b) RETURN a, t, b
|
||||
|
||||
-- With alias
|
||||
MATCH (n) RETURN n.did AS identity
|
||||
|
||||
-- Aggregations (planned)
|
||||
MATCH (n) RETURN count(n) AS total
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. Exit is Voice
|
||||
|
||||
Agents can leave, taking their data cryptographically:
|
||||
|
||||
```janus
|
||||
// Burn identity
|
||||
let burned = identity.burn(my_id)
|
||||
// After burn: no new signatures possible
|
||||
// Verification of historical signatures still works
|
||||
```
|
||||
|
||||
### 2. Profit = Honesty
|
||||
|
||||
Economic stakes align incentives:
|
||||
|
||||
- **Posting** requires $SCRAP burn
|
||||
- **Identity** requires $STASIS bond
|
||||
- **Reputation** decays without verification
|
||||
|
||||
### 3. Code is Law
|
||||
|
||||
No central moderation, only protocol rules:
|
||||
|
||||
- **Betrayal detection** via Bellman-Ford (mathematical, not subjective)
|
||||
- **Path verification** via cryptographic proofs
|
||||
- **Reputation** via Bayesian updates
|
||||
|
||||
### 4. Kenya Compliance
|
||||
|
||||
Resource-constrained environments:
|
||||
|
||||
- **Binary size:** <200KB for L1
|
||||
- **Memory:** <10MB for graph operations
|
||||
- **Storage:** Single-file embedded (libmdbx)
|
||||
- **No cloud calls:** Fully offline-capable
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all SDK tests
|
||||
zig build test-qvl
|
||||
|
||||
# Run specific module
|
||||
zig build test -- --module lexer
|
||||
|
||||
# Run with coverage (planned)
|
||||
zig build test-qvl-coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Sprint 0 ✅ — BDD Specifications
|
||||
- 58 Gherkin scenarios for QVL
|
||||
|
||||
### Sprint 1 ✅ — Storage Layer
|
||||
- libmdbx PersistentGraph
|
||||
- HybridGraph (disk + memory)
|
||||
|
||||
### Sprint 2 ✅ — GQL Parser
|
||||
- ISO/IEC 39075:2024 compliant
|
||||
- Lexer, Parser, AST, Codegen
|
||||
|
||||
### Sprint 3 🔄 — Documentation
|
||||
- API reference (this file)
|
||||
- Architecture decision records
|
||||
- Tutorial: Building your first agent
|
||||
|
||||
### Sprint 4 📅 — L4 Feed
|
||||
- DuckDB integration
|
||||
- LanceDB vector store
|
||||
- Social media primitives
|
||||
|
||||
### Sprint 5 📅 — Production
|
||||
- Performance benchmarks
|
||||
- Security audit
|
||||
- Release v1.0
|
||||
|
||||
---
|
||||
|
||||
## Related Projects
|
||||
|
||||
- [Janus Language](https://github.com/janus-lang/janus) — The foundation
|
||||
- [Libertaria Stack](https://git.maiwald.work/Libertaria) — Full protocol implementation
|
||||
- [Moltbook](https://moltbook.com) — Agent social network (lessons learned)
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT + Libertaria Commons Clause
|
||||
MIT License + Libertaria Commons Clause
|
||||
|
||||
See LICENSE for details.
|
||||
|
||||
---
|
||||
|
||||
*Forge burns bright. The Exit is being built.*
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue