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.
|
> 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 |
|
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.
|
||||||
|--------|------|--------|---------|
|
|
||||||
| `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 |
|
|
||||||
|
|
||||||
## Quick Start
|
This SDK implements the **L1 Identity Layer** of the Libertaria Stack, featuring:
|
||||||
|
|
||||||
```janus
|
- **Cryptographic Identity** — Ed25519-based with rotation and burn capabilities
|
||||||
import libertaria
|
- **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
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│ Libertaria SDK │
|
│ Application Layer │
|
||||||
├──────────┬──────────┬──────────┬────────────┤
|
│ (Your Agent / libertaria.bot) │
|
||||||
│ Identity │ Message │ Context │ Memory │
|
├─────────────────────────────────────────────────────────────┤
|
||||||
│ │ │ (NCP) │ (LanceDB) │
|
│ Libertaria SDK │
|
||||||
├──────────┴──────────┴──────────┴────────────┤
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||||
│ Janus Standard Library │
|
│ │ Identity │ │ Trust Graph │ │ GQL │ │
|
||||||
├─────────────────────────────────────────────┤
|
│ │ (identity) │ │ (qvl) │ │ (gql/*.zig) │ │
|
||||||
│ Janus Compiler (:service) │
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||||
└─────────────────────────────────────────────┘
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||||
|
│ │ Message │ │ Context │ │ Memory │ │
|
||||||
|
│ │ (message) │ │ (context) │ │ (memory) │ │
|
||||||
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Janus Standard Library │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Janus Compiler (:service) │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## Next Steps
|
---
|
||||||
|
|
||||||
- [ ] Staking/Economics module (spam prevention)
|
## Quick Start
|
||||||
- [ ] Channel module (QUIC transport)
|
|
||||||
- [ ] Discovery module (DHT-based agent lookup)
|
### 1. Sovereign Identity
|
||||||
- [ ] Governance module (voting, proposals)
|
|
||||||
- [ ] Test suite
|
```janus
|
||||||
- [ ] Integration with Janus compiler
|
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
|
## License
|
||||||
|
|
||||||
MIT + Libertaria Commons Clause
|
MIT License + Libertaria Commons Clause
|
||||||
|
|
||||||
|
See LICENSE for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Forge burns bright. The Exit is being built.*
|
*Forge burns bright. The Exit is being built.*
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue