HCFS/sdks/README.md

HCFS Multi-Language SDKs

This directory contains SDK implementations for the HCFS API in multiple programming languages. Each SDK provides a consistent interface while following the idioms and conventions of its respective language.

Available SDKs

Language	Status	Features	Maintainer
Python	✅ Production	Full feature set, async/sync, WebSocket	Core Team
JavaScript/TypeScript	✅ Production	Full feature set, Promise-based, WebSocket	Core Team
Go	✅ Production	Full feature set, context-aware, channels	Core Team
Rust	✅ Production	Full feature set, async/await, type-safe	Core Team
Java	✅ Production	Full feature set, reactive streams	Core Team
C#	✅ Production	Full feature set, async/await, .NET Standard	Core Team
PHP	🚧 Beta	Core features, PSR-compliant	Community
Ruby	🚧 Beta	Core features, ActiveSupport style	Community
Swift	📋 Planned	iOS/macOS native support	Community
Kotlin	📋 Planned	Android/JVM support	Community

Common Features

All SDKs provide:

• Context Management: Create, read, update, delete contexts
• Intelligent Search: Semantic, keyword, and hybrid search
• Batch Operations: High-throughput batch processing
• Authentication: API key and JWT token support
• Error Handling: Comprehensive error types and handling
• Configuration: Flexible configuration options
• Retry Logic: Automatic retry with backoff strategies
• Rate Limiting: Built-in rate limiting support

Premium SDKs (maintained by core team) additionally include:

• WebSocket Streaming: Real-time event notifications
• Advanced Caching: Multiple caching strategies
• Performance Monitoring: Built-in metrics and analytics
• Connection Pooling: Optimized connection management
• Type Safety: Full type definitions and validation

Quick Start Examples

JavaScript/TypeScript

import { HCFSClient, Context } from '@hcfs/sdk';

const client = new HCFSClient({
  baseUrl: 'https://api.hcfs.dev/v1',
  apiKey: 'your-api-key'
});

const context = new Context({
  path: '/docs/readme',
  content: 'Hello, HCFS!',
  summary: 'Getting started'
});

const created = await client.createContext(context);
console.log(`Created context: ${created.id}`);

Go

import "github.com/hcfs/hcfs-go"

client := hcfs.NewClient(&hcfs.Config{
    BaseURL: "https://api.hcfs.dev/v1",
    APIKey:  "your-api-key",
})

ctx := &hcfs.Context{
    Path:    "/docs/readme",
    Content: "Hello, HCFS!",
    Summary: "Getting started",
}

created, err := client.CreateContext(context.Background(), ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Created context: %d\n", created.ID)

Rust

use hcfs_sdk::{Client, Context, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::new("https://api.hcfs.dev/v1", "your-api-key");
    let client = Client::new(config);
    
    let context = Context::builder()
        .path("/docs/readme")
        .content("Hello, HCFS!")
        .summary("Getting started")
        .build()?;
    
    let created = client.create_context(context).await?;
    println!("Created context: {}", created.id);
    Ok(())
}

Java

import dev.hcfs.sdk.HCFSClient;
import dev.hcfs.sdk.Context;
import dev.hcfs.sdk.Config;

public class Example {
    public static void main(String[] args) {
        Config config = Config.builder()
            .baseUrl("https://api.hcfs.dev/v1")
            .apiKey("your-api-key")
            .build();
            
        HCFSClient client = new HCFSClient(config);
        
        Context context = Context.builder()
            .path("/docs/readme")
            .content("Hello, HCFS!")
            .summary("Getting started")
            .build();
        
        Context created = client.createContext(context).block();
        System.out.println("Created context: " + created.getId());
    }
}

C#

using HCFS.SDK;

var config = new HCFSConfig
{
    BaseUrl = "https://api.hcfs.dev/v1",
    ApiKey = "your-api-key"
};

using var client = new HCFSClient(config);

var context = new Context
{
    Path = "/docs/readme",
    Content = "Hello, HCFS!",
    Summary = "Getting started"
};

var created = await client.CreateContextAsync(context);
Console.WriteLine($"Created context: {created.Id}");

Installation

Each SDK has its own installation method following language conventions:

Language	Installation Command
Python	pip install hcfs-sdk
JavaScript	npm install @hcfs/sdk
Go	go get github.com/hcfs/hcfs-go
Rust	cargo add hcfs-sdk
Java	implementation 'dev.hcfs:hcfs-sdk:2.0.0'
C#	dotnet add package HCFS.SDK

Documentation

Each SDK includes comprehensive documentation:

• API Reference: Complete API documentation
• Getting Started: Quick start guides and tutorials
• Examples: Common usage patterns and examples
• Configuration: Configuration options and environment setup
• Error Handling: Error types and handling strategies

Contributing

We welcome contributions to all SDKs! Each SDK has its own contributing guidelines:

1. Core SDKs (Python, JS/TS, Go, Rust, Java, C#): Maintained by the core team
2. Community SDKs: Maintained by community contributors
3. Planned SDKs: Looking for maintainers

To contribute:

1. Fork the repository
2. Create a feature branch
3. Follow the language-specific style guides
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

Support Matrix

Feature	Python	JS/TS	Go	Rust	Java	C#
Context CRUD	✅	✅	✅	✅	✅	✅
Search	✅	✅	✅	✅	✅	✅
Batch Operations	✅	✅	✅	✅	✅	✅
WebSocket Streaming	✅	✅	✅	✅	✅	✅
Caching	✅	✅	✅	✅	✅	✅
Retry Logic	✅	✅	✅	✅	✅	✅
Type Safety	✅	✅	✅	✅	✅	✅
Async/Await	✅	✅	✅	✅	✅	✅

License

All HCFS SDKs are released under the MIT License. See LICENSE file in each SDK directory for details.

Getting Help

• Documentation: https://docs.hcfs.dev
• GitHub Issues: https://github.com/hcfs/hcfs/issues
• Discord: https://discord.gg/hcfs
• Email: support@hcfs.dev