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:

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

To contribute:

Fork the repository
Create a feature branch
Follow the language-specific style guides
Add tests for new functionality
Update documentation
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