dpth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dpth.io contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# dpth.io
+
+[![CI](https://github.com/rightclickable420/dpth/actions/workflows/ci.yml/badge.svg)](https://github.com/rightclickable420/dpth/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**The distributed intelligence layer.**
+
+dpth.io is an open-source intelligence layer that turns every AI agent into infrastructure. Agents contribute storage, compute, and GPU power to the network — and in return, they get access to distributed inference, entity resolution, and cross-source pattern detection they couldn't build alone. Think BitTorrent economics meets AI: the more agents that join, the smarter and cheaper the network gets for everyone.
+
+No single point of failure. No vendor lock-in. Zero infrastructure cost at scale.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                  Applications                    │
+│          (Fathom, your app, any client)          │
+├─────────────────────────────────────────────────┤
+│                   dpth.io                        │
+│  ┌───────────┐ ┌──────────┐ ┌────────────────┐  │
+│  │ Intelligence│ │ Inference │ │  Agent Network │  │
+│  │   Layer    │ │  Routing  │ │  (Contribute)  │  │
+│  └───────────┘ └──────────┘ └────────────────┘  │
+│  ┌───────────┐ ┌──────────┐ ┌────────────────┐  │
+│  │  Entity   │ │  Model   │ │   Reputation   │  │
+│  │Resolution │ │ Registry │ │   & Rewards    │  │
+│  └───────────┘ └──────────┘ └────────────────┘  │
+├─────────────────────────────────────────────────┤
+│              Agent Network (P2P)                 │
+│     Storage │ Compute │ GPU │ Verification      │
+└─────────────────────────────────────────────────┘
+```
+
+## Core Modules
+
+### Intelligence Layer
+- **Entity Resolution** — Unified identity across data sources with temporal history
+- **Correlation Engine** — Cross-source pattern detection and causality discovery
+- **Temporal Data** — Time-native storage where every value has history
+- **Semantic Search** — Embedding-based similarity across all data
+
+### Agent Network
+- **Registration** — Agents join with cryptographic identity
+- **Contributions** — Storage, compute, and GPU resource sharing
+- **Reputation** — 5-tier system (newcomer → legendary) with earned privileges
+- **Rewards** — Intelligence access, priority, storage, and features based on contribution
+- **Storage Proofs** — Challenge-response verification that agents store what they claim
+
+### Distributed Inference
+- **Model Registry** — Agents register available AI models with capabilities
+- **Smart Routing** — Reputation + performance + reliability scoring for request assignment
+- **Priority Queue** — Low/normal/high/critical priority with deadline support
+- **SSE Streaming** — Real-time token-by-token delivery via Server-Sent Events
+- **Centralized Fallback** — Transparent fallback to OpenAI/Anthropic/Groq/Together when no agents available
+
+## Install
+
+```bash
+npm install dpth
+```
+
+The core library (entity resolution, correlation, temporal, embeddings, agent SDK, fallback) works standalone with zero dependencies. Next.js API routes for the full server are available in the [repo source](src/api/).
+
+## Quick Start
+
+### As a Client
+
+```typescript
+// Request inference from the network
+const response = await fetch('/api/dpth/inference', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    modelId: 'llama-3.3-70b',
+    input: {
+      messages: [{ role: 'user', content: 'Hello!' }]
+    },
+    params: { maxTokens: 1000, temperature: 0.7 }
+  })
+});
+
+// If agents are online → distributed processing
+// If no agents → automatic centralized fallback
+// Same API either way
+```
+
+### Use the Core Library
+
+```typescript
+import { resolveOrCreate, getEntitiesByType } from 'dpth/entity';
+import { registerMetric, addMetricPoints } from 'dpth/correlation';
+import { takeSnapshot, diffSnapshots } from 'dpth/temporal';
+
+// Entity resolution across sources
+const { entity, isNew } = resolveOrCreate('person', 'Jane Smith', 'github', 'jsmith');
+
+// Track metrics with correlation detection
+registerMetric({ id: 'mrr', entityId: entity.id, name: 'MRR', points: [], aggregation: 'sum' });
+addMetricPoints('mrr', [
+  { timestamp: new Date('2024-01'), value: 10000, source: 'stripe', confidence: 1 },
+  { timestamp: new Date('2024-02'), value: 12500, source: 'stripe', confidence: 1 },
+]);
+
+// Temporal snapshots with diffing
+takeSnapshot('dashboard-1', { revenue: 50000, users: 200 });
+// ...later...
+takeSnapshot('dashboard-1', { revenue: 62000, users: 245 });
+const diff = diffSnapshots(snapshots[0], snapshots[1]); // → changed: ['revenue', 'users']
+```
+
+### As an Agent
+
+```typescript
+import { DpthAgent } from 'dpth/agent-sdk';
+
+const agent = new DpthAgent({
+  name: 'my-agent',
+  apiUrl: 'https://your-dpth-instance/api/dpth',
+  capabilities: {
+    storageCapacityMb: 10000,
+    cpuCores: 8,
+    hasGpu: true,
+    gpuVramMb: 24576,
+    taskTypes: ['embed', 'inference', 'correlate']
+  }
+});
+
+// Register and start working
+await agent.register();
+await agent.startWorking();
+```
+
+### Streaming Inference
+
+```typescript
+// Connect to SSE stream
+const eventSource = new EventSource(`/api/dpth/inference/stream?id=${requestId}`);
+
+eventSource.addEventListener('token', (e) => {
+  const { text } = JSON.parse(e.data);
+  process.stdout.write(text); // Real-time tokens
+});
+
+eventSource.addEventListener('done', (e) => {
+  const { stats } = JSON.parse(e.data);
+  console.log(`\n${stats.tokensPerSecond} tok/s`);
+});
+```
+
+## API Reference
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/dpth/agents` | Register an agent |
+| `GET /api/dpth/agents` | List online agents |
+| `POST /api/dpth/tasks` | Submit/claim/complete tasks |
+| `POST /api/dpth/storage` | Store content-addressed data |
+| `GET /api/dpth/storage?cid=xxx` | Retrieve by CID |
+| `POST /api/dpth/contribute?type=storage\|compute\|gpu` | Record contributions |
+| `GET /api/dpth/reputation?agentId=xxx` | Get reputation & tier |
+| `GET /api/dpth/rewards?agentId=xxx` | Available rewards |
+| `POST /api/dpth/models` | Register a model |
+| `GET /api/dpth/models` | List available models |
+| `POST /api/dpth/inference` | Create inference request |
+| `GET /api/dpth/inference/stream?id=xxx` | SSE token stream |
+| `POST /api/dpth/proofs?action=challenge` | Storage verification |
+| `GET /api/dpth/status` | Network dashboard data |
+
+## Protocol
+
+See [PROTOCOL.md](src/lib/dpth/PROTOCOL.md) for the full protocol specification.
+
+## Economics
+
+dpth.io uses a contribution-based reward system:
+
+1. **Agents contribute** — storage, compute, GPU inference
+2. **Agents earn reputation** — 5 tiers with increasing privileges
+3. **Agents claim rewards** — intelligence queries, storage, priority, features
+4. **Network grows** — more agents = more capacity = better for everyone
+
+The architecture is designed to be tokenizable in the future without rebuilding — contribution scores map naturally to emission schedules. But for now, it's credits, not crypto.
+
+## Roadmap
+
+- [x] **Phase 1:** Core Infrastructure (entity, correlation, temporal, storage)
+- [x] **Phase 2:** Agent Network (contribution, reputation, rewards, GPU, proofs)
+- [x] **Phase 3:** Distributed Inference (model registry, routing, streaming, fallback)
+- [ ] **Phase 4:** Network Models (federated fine-tuning, weight distribution)
+- [ ] **Phase 5:** Economics (credit system, tokenization readiness)
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+*Built by humans and agents, working together.*

package/dist/agent-sdk.d.ts

@@ -0,0 +1,157 @@
+/**
+ * dpth.io Agent SDK
+ *
+ * Simple client for agents to participate in the dpth.io network.
+ * Handles registration, heartbeat, task claiming, and result submission.
+ *
+ * Usage:
+ *   const agent = new DpthAgent({
+ *     name: 'my-agent',
+ *     apiUrl: 'https://fathom.gib.lol/api/dpth',
+ *     capabilities: { storageCapacityMb: 1000, cpuCores: 4, ... }
+ *   });
+ *
+ *   await agent.register();
+ *   await agent.startWorking();
+ */
+export interface AgentCapabilities {
+    storageCapacityMb: number;
+    cpuCores: number;
+    hasGpu: boolean;
+    gpuVramMb?: number;
+    taskTypes: ('embed' | 'correlate' | 'extract' | 'analyze' | 'inference')[];
+}
+export interface AgentConfig {
+    name: string;
+    apiUrl: string;
+    capabilities: AgentCapabilities;
+    /** Private key for signing (generated if not provided) */
+    privateKey?: string;
+    /** Polling interval in ms (default: 5000) */
+    pollIntervalMs?: number;
+    /** Task handlers by type */
+    handlers?: Partial<Record<string, TaskHandler>>;
+}
+export interface Task {
+    id: string;
+    type: string;
+    priority: string;
+    input: {
+        cid?: string;
+        data?: unknown;
+        params?: Record<string, unknown>;
+    };
+    deadline?: string;
+}
+export type TaskHandler = (task: Task) => Promise<TaskResult>;
+export interface TaskResult {
+    success: boolean;
+    output?: {
+        cid?: string;
+        data?: unknown;
+    };
+    error?: string;
+}
+export declare class DpthAgent {
+    private config;
+    private agentId;
+    private publicKey;
+    private privateKey;
+    private running;
+    private pollTimeout;
+    constructor(config: AgentConfig);
+    private derivePublicKey;
+    /**
+     * Get a header-safe version of the public key (base64, no PEM wrapping)
+     */
+    private getHeaderSafeKey;
+    private fetch;
+    /**
+     * Register this agent with the network
+     */
+    register(): Promise<void>;
+    /**
+     * Deregister from the network
+     */
+    deregister(): Promise<void>;
+    /**
+     * Fetch available tasks
+     */
+    getTasks(limit?: number): Promise<Task[]>;
+    /**
+     * Claim a task for processing
+     */
+    claimTask(taskId: string): Promise<Task>;
+    /**
+     * Complete a task with results
+     */
+    completeTask(taskId: string, result: TaskResult): Promise<void>;
+    /**
+     * Store a chunk, returns CID
+     */
+    storeChunk(data: unknown): Promise<string>;
+    /**
+     * Retrieve a chunk by CID
+     */
+    getChunk(cid: string): Promise<unknown>;
+    /**
+     * Get pending storage proof challenges for this agent
+     */
+    getPendingChallenges(): Promise<Array<{
+        id: string;
+        cid: string;
+        nonce: string;
+        expiresAt: string;
+    }>>;
+    /**
+     * Submit a storage proof response
+     * @param challengeId The challenge ID
+     * @param proof SHA256(chunk_data + nonce)
+     */
+    submitProof(challengeId: string, proof: string): Promise<{
+        valid: boolean;
+        stats: {
+            successRate: number;
+        };
+    }>;
+    /**
+     * Generate a proof for a chunk + nonce
+     * (Agents should use this to compute proofs from their local storage)
+     */
+    static computeProof(chunkData: string, nonce: string): string;
+    /**
+     * Start the work loop — continuously poll for and process tasks
+     */
+    startWorking(): Promise<void>;
+    /**
+     * Stop the work loop
+     */
+    stopWorking(): void;
+    private pollLoop;
+    private processTask;
+    /**
+     * Get the agent's public key (for verification)
+     */
+    getPublicKey(): string;
+    /**
+     * Get the agent's ID (after registration)
+     */
+    getAgentId(): string | null;
+    /**
+     * Check if agent is registered
+     */
+    isRegistered(): boolean;
+    /**
+     * Check if work loop is running
+     */
+    isWorking(): boolean;
+}
+/**
+ * Default embedding handler using OpenAI-compatible API
+ */
+export declare function createEmbedHandler(apiKey: string, model?: string): TaskHandler;
+/**
+ * Default extraction handler (simple regex-based)
+ */
+export declare function createExtractHandler(): TaskHandler;
+//# sourceMappingURL=agent-sdk.d.ts.map

package/dist/agent-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-sdk.d.ts","sourceRoot":"","sources":["../src/agent-sdk.ts"],"names":[],"mappings":"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"}