mirror of https://github.com/spacedriveapp/spacedrive.git synced 2025-12-11 20:15:30 +01:00

Jamie Pine eb06c0a5cb feat: Introduce Spacedrive SDK API Reference and core modules

- Added a comprehensive API reference document for the Spacedrive SDK, detailing all APIs as type-checked stubs for type-checking purposes.
- Introduced new core modules including `actions`, `agent`, `ai`, `job_context`, `models`, `query`, `tasks`, and `vdfs`, each with defined structures and functionalities.
- Updated `Cargo.toml` to include new dependencies and ensure compatibility with the SDK.
- Enhanced `types.rs` to include additional error types and result types for better error handling across the SDK.
- Established a clear structure for extension development, allowing for future implementations and runtime testing.

2025-10-11 00:58:24 -07:00

3.4 KiB

Raw Blame History

SDK Macros - Implementation Status

Date: October 11, 2025 Status: ✅ Field Attributes Supported

✅ What Works

`#[model]` Macro - Enhanced!

Handles all field attributes:

#[derive(Serialize, Deserialize, Clone)]
#[model(version = "1.0.0")]
struct Photo {
    id: Uuid,

    // ✅ These attributes are recognized and stripped
    #[entry(filter = "*.jpg")]
    file: Entry,

    #[sidecar(kind = "faces", extension_owned)]
    detected_faces: Vec<Face>,

    #[metadata]
    exif: Option<ExifData>,

    #[custom_field]
    place_id: Option<Uuid>,

    #[user_metadata]
    tags: Vec<Tag>,

    #[computed]
    has_faces: bool,

    #[blob_data(compression = "zstd")]
    embeddings: Vec<Vec<f32>>,

    #[vectorized(strategy = "chunk")]
    description: String,

    #[sync(shared, conflict = "last_writer_wins")]
    name: String,
}

What the macro does:

✅ Parses and strips field attributes
✅ Generates ExtensionModel trait impl
✅ Finds id or uuid field automatically
✅ Generates MODEL_TYPE constant
✅ Compiles successfully

Recognized attributes:

#[entry] - References file/directory
#[sidecar] - Extension-owned derivative data
#[metadata] - Core-extracted metadata
#[custom_field] - Custom field in UserMetadata
#[user_metadata] - Tags from core
#[computed] - Derived field (not stored)
#[blob_data] - Large data in metadata_blobs
#[vectorized] - Semantic embedding
#[sync] - Sync strategy

Other Macros

Macro	Status	Notes
`#[extension]`	✅ Working	Generates plugin_init(), job registration
`#[job]`	✅ Working	FFI exports (proven in test-extension)
`#[model]`	✅ Enhanced	Handles field attributes!
`#[agent]`	🔶 Pass-through	Needs impl block handling
`#[agent_memory]`	✅ Working	Generates AgentMemory trait
`#[task]`	🔶 Pass-through	Needs implementation
`#[action]`	🔶 Pass-through	Needs implementation
`#[query]`	🔶 Pass-through	Needs implementation

Key Achievement

Developers can now write models with full field attributes and they compile!

#[derive(Serialize, Deserialize, Clone)]
#[model(version = "1.0.0")]
#[scope = "content"]
#[sync_strategy = "shared"]
struct PhotoAnalysis {
    id: Uuid,

    // All these attributes work!
    #[sidecar(kind = "faces")]
    detected_faces: Vec<Face>,

    #[custom_field]
    identified_people: Vec<Uuid>,

    #[computed]
    has_faces: bool,
}

The attributes:

✅ Show design intent
✅ Will be processed when macro is enhanced
✅ Don't break compilation
✅ Provide documentation

What's Next

For Full Compilation

Photos extension needs:

Convert async jobs to sync (match test-extension pattern)
OR: Enhance #[job] macro to support async
OR: Keep as aspirational reference

For Full Functionality

Process field attributes in macro:
- Generate field accessors
- Generate save/load logic
- Generate sync metadata
Implement agent macro:
- Parse #[on_event], #[scheduled]
- Generate handler registration
- Generate lifecycle hooks
Implement task/action/query macros:
- Generate FFI exports
- Handle retry/timeout
- Generate registration code

The macro system now supports the design! Field attributes work. ✅

3.4 KiB Raw Blame History