feat: add Dart SDK for Alphahuman Memory API (#12)

Author: oxoxDev

packages/sdk-dart/.gitignore

@@ -0,0 +1,4 @@
+.dart_tool/
+.packages
+build/
+pubspec.lock

packages/sdk-dart/.gitkeep

@@ -0,0 +1,13 @@
+.PHONY: build test integration-test clean
+
+build:
+	dart analyze
+
+test:
+	dart test test/alphahuman_memory_client_test.dart
+
+integration-test:
+	dart test test/integration_test.dart
+
+clean:
+	rm -rf .dart_tool build

packages/sdk-dart/Makefile

@@ -0,0 +1 @@
+include: package:lints/recommended.yaml

packages/sdk-dart/analysis_options.yaml

@@ -0,0 +1,49 @@
+import 'dart:io' show Platform;
+
+import 'package:alphahuman_sdk/alphahuman_sdk.dart';
+
+Future<void> main() async {
+  final token = Platform.environment['ALPHAHUMAN_TOKEN'];
+  if (token == null || token.isEmpty) {
+    print('Set ALPHAHUMAN_TOKEN environment variable to run this example.');
+    return;
+  }
+
+  final client = AlphahumanMemoryClient(token);
+
+  try {
+    // Insert a memory
+    final insertResp = await client.insertMemory(InsertMemoryParams(
+      title: 'example-doc',
+      content: 'Dart was created by Google and first appeared in 2011.',
+      namespace: 'example-ns',
+    ));
+    print('Insert: success=${insertResp.success}, status=${insertResp.status}');
+
+    // Recall context
+    final recallResp = await client.recallMemory(
+        RecallMemoryParams(namespace: 'example-ns'));
+    print('Recall: success=${recallResp.success}, cached=${recallResp.cached}');
+
+    // Query memory
+    final queryResp = await client.queryMemory(QueryMemoryParams(
+      query: 'When was Dart created?',
+      namespace: 'example-ns',
+    ));
+    print('Query: success=${queryResp.success}, response=${queryResp.response}');
+
+    // Recall memories (Ebbinghaus)
+    final memoriesResp = await client.recallMemories(
+        RecallMemoriesParams(namespace: 'example-ns'));
+    print('Memories: success=${memoriesResp.success}, '
+        'count=${memoriesResp.memories.length}');
+
+    // Delete memory
+    final deleteResp = await client.deleteMemory(
+        DeleteMemoryParams(namespace: 'example-ns'));
+    print('Delete: success=${deleteResp.success}, '
+        'nodesDeleted=${deleteResp.nodesDeleted}');
+  } finally {
+    client.close();
+  }
+}

packages/sdk-dart/example/example.dart

@@ -0,0 +1,5 @@
+library alphahuman_sdk;
+
+export 'src/alphahuman_error.dart';
+export 'src/types.dart';
+export 'src/alphahuman_memory_client.dart';

packages/sdk-dart/lib/alphahuman_sdk.dart

@@ -0,0 +1,10 @@
+class AlphahumanError implements Exception {
+  final String message;
+  final int status;
+  final String body;
+
+  AlphahumanError(this.message, this.status, [this.body = '']);
+
+  @override
+  String toString() => 'AlphahumanError($status): $message';
+}

packages/sdk-dart/lib/src/alphahuman_error.dart

@@ -0,0 +1,109 @@
+import 'dart:convert';
+import 'dart:io' show Platform;
+
+import 'package:http/http.dart' as http;
+
+import 'alphahuman_error.dart';
+import 'types.dart';
+
+class AlphahumanMemoryClient {
+  static const _defaultBaseUrl = 'https://staging-api.alphahuman.xyz';
+
+  final String _token;
+  final String _baseUrl;
+  final http.Client _httpClient;
+  final bool _ownsClient;
+
+  AlphahumanMemoryClient(
+    String token, {
+    String? baseUrl,
+    http.Client? httpClient,
+  })  : _token = token,
+        _baseUrl = (baseUrl ??
+                Platform.environment['ALPHAHUMAN_BASE_URL'] ??
+                _defaultBaseUrl)
+            .replaceAll(RegExp(r'/+$'), ''),
+        _httpClient = httpClient ?? http.Client(),
+        _ownsClient = httpClient == null {
+    if (token.trim().isEmpty) {
+      throw ArgumentError('token is required');
+    }
+  }
+
+  Future<InsertMemoryResponse> insertMemory(InsertMemoryParams params) async {
+    params.validate();
+    final result = await _post('/v1/memory/insert', params.toJson());
+    return InsertMemoryResponse.fromJson(result);
+  }
+
+  Future<RecallMemoryResponse> recallMemory([RecallMemoryParams? params]) async {
+    params ??= RecallMemoryParams();
+    params.validate();
+    final result = await _post('/v1/memory/recall', params.toJson());
+    return RecallMemoryResponse.fromJson(result);
+  }
+
+  Future<DeleteMemoryResponse> deleteMemory([DeleteMemoryParams? params]) async {
+    params ??= DeleteMemoryParams();
+    params.validate();
+    final result = await _post('/v1/memory/admin/delete', params.toJson());
+    return DeleteMemoryResponse.fromJson(result);
+  }
+
+  Future<QueryMemoryResponse> queryMemory(QueryMemoryParams params) async {
+    params.validate();
+    final result = await _post('/v1/memory/query', params.toJson());
+    return QueryMemoryResponse.fromJson(result);
+  }
+
+  Future<RecallMemoriesResponse> recallMemories(
+      [RecallMemoriesParams? params]) async {
+    params ??= RecallMemoriesParams();
+    params.validate();
+    final result = await _post('/v1/memory/memories/recall', params.toJson());
+    return RecallMemoriesResponse.fromJson(result);
+  }
+
+  Future<Map<String, dynamic>> _post(
+      String path, Map<String, dynamic> body) async {
+    final url = Uri.parse('$_baseUrl$path');
+    final response = await _httpClient.post(
+      url,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': 'Bearer $_token',
+      },
+      body: jsonEncode(body),
+    );
+    return _handleResponse(response);
+  }
+
+  Map<String, dynamic> _handleResponse(http.Response response) {
+    Map<String, dynamic> json;
+    try {
+      json = response.body.isNotEmpty
+          ? jsonDecode(response.body) as Map<String, dynamic>
+          : <String, dynamic>{};
+    } catch (_) {
+      throw AlphahumanError(
+        'HTTP ${response.statusCode}: non-JSON response',
+        response.statusCode,
+        response.body,
+      );
+    }
+
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      final message =
+          json['error'] as String? ?? 'HTTP ${response.statusCode}';
+      throw AlphahumanError(message, response.statusCode, response.body);
+    }
+
+    return json;
+  }
+
+  void close() {
+    if (_ownsClient) {
+      _httpClient.close();
+    }
+  }
+}