Skip to content
HeliosDB HeliosDB Nano

HeliosDB Nano v3.0.0 - Quick Fix Guide

HeliosDB Nano v3.0.0 - Quick Fix Guide

Status: Ready to Execute Estimated Time: 2.5 hours Skill Level: Intermediate Rust

Quick Start (10 Minutes to Compilable)

Step 1: Add Dependencies (2 minutes)

Terminal window
cd /home/claude/HeliosDB Nano

Edit Cargo.toml, add after line 34:

futures = "0.3"
async-stream = "0.3"

Test:

Terminal window
cargo check 2>&1 | grep -E "(futures|async_stream)" | grep "unresolved"
# Should output nothing

Step 2: Fix ApiError::internal() (2 minutes)

Edit src/api/models/error.rs, add after line 84:

    /// Create an internal error (500) - alias for internal_server_error
    pub fn internal(message: impl Into<String>) -> Self {
        Self::internal_server_error(message)
    }

Test:

Terminal window
cargo check 2>&1 | grep "ApiError.*internal" | grep "error"
# Should output nothing

Step 3: Create ApiResponse Type (5 minutes)

Edit src/api/models/mod.rs, add after line 7:

/// Generic API response wrapper
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiResponse<T> {
    pub data: T,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub meta: Option<serde_json::Value>,
}


impl<T> ApiResponse<T> {
    pub fn new(data: T) -> Self {
        Self { data, meta: None }
    }


    pub fn with_meta(data: T, meta: serde_json::Value) -> Self {
        Self { data, meta: Some(meta) }
    }
}

Add to re-exports (after line 21):

pub use ApiResponse;

Test:

Terminal window
cargo check 2>&1 | grep "ApiResponse" | grep "unresolved"
# Should output nothing

Step 4: Fix println! Syntax (1 minute)

Edit src/repl/commands.rs, line 997:

Before:

println!("     schema = db.generate_schema(\"{}\")".cyan(), description);

After:

println!("     schema = db.generate_schema(\"{}\")", description.cyan());

Main Work: Add Stub Methods (2 hours)

Part A: Add Support Types (15 minutes)

Edit src/types.rs, add at end of file:

// API Support Types


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct VectorStoreInfo {
    pub name: String,
    pub dimensions: usize,
    pub metric: String,
    pub index_type: String,
    pub count: usize,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct VectorSearchResult {
    pub id: String,
    pub score: f32,
    pub metadata: Option<serde_json::Value>,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct VectorResult {
    pub id: String,
    pub vector: Vec<f32>,
    pub metadata: Option<serde_json::Value>,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct AgentSessionInfo {
    pub session_id: String,
    pub name: String,
    pub config: serde_json::Value,
    pub created_at: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct AgentMessage {
    pub id: String,
    pub role: String,
    pub content: String,
    pub metadata: Option<serde_json::Value>,
    pub timestamp: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DocumentInfo {
    pub doc_id: String,
    pub metadata: serde_json::Value,
    pub chunk_count: usize,
    pub created_at: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DocumentChunk {
    pub chunk_id: String,
    pub content: String,
    pub index: usize,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DocumentSearchResult {
    pub doc_id: String,
    pub score: f32,
    pub chunk: DocumentChunk,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RAGResult {
    pub content: String,
    pub source: String,
    pub score: f32,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct SchemaTemplate {
    pub name: String,
    pub description: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ChatModelInfo {
    pub model_id: String,
    pub name: String,
    pub provider: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ChatMessage {
    pub role: String,
    pub content: String,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ChatCompletionResponse {
    pub message: ChatMessage,
    pub usage: serde_json::Value,
}


#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct CreateDocumentRequest {
    pub content: String,
    pub metadata: serde_json::Value,
    pub chunk_size: usize,
    pub chunk_overlap: usize,
}

Update lib.rs (line 104), add:

pub use types::{
    VectorStoreInfo, VectorSearchResult, VectorResult,
    AgentSessionInfo, AgentMessage,
    DocumentInfo, DocumentChunk, DocumentSearchResult, RAGResult,
    SchemaTemplate, ChatModelInfo, ChatMessage, ChatCompletionResponse,
    CreateDocumentRequest,
};

Part B: Add Stub Methods (1h 45min)

Critical: See /home/claude/HeliosDB Nano/BUILD_FIX_PLAN.md Phase 2 for complete method implementations.

Edit src/lib.rs, add at end of impl EmbeddedDatabase block (before the final }):

Template for all stub methods:

    // Vector Store Operations (8 methods)
    pub fn list_vector_stores(&self) -> Result<Vec<VectorStoreInfo>> {
        Ok(vec![])
    }


    pub fn create_vector_store(
        &self,
        name: &str,
        dimensions: usize,
        metric: &str,
        index_type: &str,
        hnsw_m: usize,
        hnsw_ef: usize,
    ) -> Result<VectorStoreInfo> {
        Err(Error::Generic("Vector store creation not yet implemented".to_string()))
    }


    pub fn get_vector_store(&self, name: &str) -> Result<VectorStoreInfo> {
        Err(Error::Generic(format!("Vector store '{}' not found", name)))
    }


    pub fn delete_vector_store(&self, name: &str) -> Result<()> {
        Ok(())
    }


    pub fn insert_vectors(
        &self,
        store: &str,
        vectors: Vec<(String, Vec<f32>, Option<serde_json::Value>)>,
    ) -> Result<Vec<String>> {
        Ok(vec![])
    }


    pub fn upsert_vectors(
        &self,
        store: &str,
        vectors: Vec<(String, Vec<f32>, Option<serde_json::Value>)>,
    ) -> Result<Vec<String>> {
        Ok(vec![])
    }


    pub fn search_vectors(
        &self,
        store: &str,
        query: &[f32],
        limit: usize,
        filter: Option<&str>,
    ) -> Result<Vec<VectorSearchResult>> {
        Ok(vec![])
    }


    pub fn delete_vectors(&self, store: &str, ids: Vec<String>) -> Result<u64> {
        Ok(0)
    }


    pub fn fetch_vectors(&self, store: &str, ids: Vec<String>) -> Result<Vec<VectorResult>> {
        Ok(vec![])
    }


    // Text/Hybrid Search (3 methods)
    pub fn text_search(
        &self,
        store: &str,
        query: &str,
        limit: usize,
        filter: Option<&str>,
    ) -> Result<Vec<VectorSearchResult>> {
        Ok(vec![])
    }


    pub fn store_texts(
        &self,
        store: &str,
        texts: Vec<(String, String, Option<serde_json::Value>)>,
    ) -> Result<Vec<String>> {
        Ok(vec![])
    }


    pub fn hybrid_search(
        &self,
        store: &str,
        query: &str,
        vector_weight: f32,
        keyword_weight: f32,
        limit: usize,
    ) -> Result<Vec<VectorSearchResult>> {
        Ok(vec![])
    }


    pub fn create_embeddings(&self, texts: Vec<String>, model: &str) -> Result<Vec<Vec<f32>>> {
        Ok(vec![])
    }


    // Agent Session Management (12 methods)
    pub fn create_agent_session(&self, name: &str, config: serde_json::Value) -> Result<String> {
        Ok(uuid::Uuid::new_v4().to_string())
    }


    pub fn list_agent_sessions(&self) -> Result<Vec<AgentSessionInfo>> {
        Ok(vec![])
    }


    pub fn get_agent_session(&self, session_id: &str) -> Result<AgentSessionInfo> {
        Err(Error::Generic(format!("Agent session '{}' not found", session_id)))
    }


    pub fn update_agent_session(&self, session_id: &str, config: serde_json::Value) -> Result<()> {
        Ok(())
    }


    pub fn delete_agent_session(&self, session_id: &str) -> Result<()> {
        Ok(())
    }


    pub fn fork_agent_session(&self, session_id: &str, new_name: &str) -> Result<String> {
        Ok(uuid::Uuid::new_v4().to_string())
    }


    pub fn add_agent_message(
        &self,
        session_id: &str,
        role: &str,
        content: &str,
        metadata: Option<serde_json::Value>,
    ) -> Result<String> {
        Ok(uuid::Uuid::new_v4().to_string())
    }


    pub fn add_agent_messages_batch(
        &self,
        session_id: &str,
        messages: Vec<AgentMessage>,
    ) -> Result<Vec<String>> {
        Ok(vec![])
    }


    pub fn get_agent_messages(
        &self,
        session_id: &str,
        limit: Option<usize>,
        offset: Option<usize>,
    ) -> Result<Vec<AgentMessage>> {
        Ok(vec![])
    }


    pub fn clear_agent_messages(&self, session_id: &str) -> Result<u64> {
        Ok(0)
    }


    pub fn get_agent_context(&self, session_id: &str, window_size: usize) -> Result<serde_json::Value> {
        Ok(serde_json::json!({}))
    }


    pub fn search_agent_memory(
        &self,
        session_id: &str,
        query: &str,
        limit: usize,
    ) -> Result<Vec<AgentMessage>> {
        Ok(vec![])
    }


    pub fn summarize_agent_memory(&self, session_id: &str) -> Result<String> {
        Ok(String::new())
    }


    // Document Management (11 methods)
    pub fn create_document(
        &self,
        content: &str,
        metadata: serde_json::Value,
        chunk_size: usize,
        chunk_overlap: usize,
    ) -> Result<DocumentInfo> {
        Err(Error::Generic("Document creation not yet implemented".to_string()))
    }


    pub fn batch_create_documents(
        &self,
        documents: Vec<CreateDocumentRequest>,
    ) -> Result<Vec<DocumentInfo>> {
        Ok(vec![])
    }


    pub fn list_documents(&self, limit: Option<usize>, offset: Option<usize>) -> Result<Vec<DocumentInfo>> {
        Ok(vec![])
    }


    pub fn get_document(&self, doc_id: &str) -> Result<DocumentInfo> {
        Err(Error::Generic(format!("Document '{}' not found", doc_id)))
    }


    pub fn get_document_chunks(&self, doc_id: &str) -> Result<Vec<DocumentChunk>> {
        Ok(vec![])
    }


    pub fn update_document(&self, doc_id: &str, metadata: serde_json::Value) -> Result<()> {
        Ok(())
    }


    pub fn delete_document(&self, doc_id: &str) -> Result<()> {
        Ok(())
    }


    pub fn rechunk_document(
        &self,
        doc_id: &str,
        chunk_size: usize,
        chunk_overlap: usize,
    ) -> Result<DocumentInfo> {
        Err(Error::Generic("Rechunking not yet implemented".to_string()))
    }


    pub fn search_documents(
        &self,
        query: &str,
        limit: usize,
        filter: Option<&str>,
    ) -> Result<Vec<DocumentSearchResult>> {
        Ok(vec![])
    }


    pub fn find_similar_documents(&self, doc_id: &str, limit: usize) -> Result<Vec<DocumentSearchResult>> {
        Ok(vec![])
    }


    pub fn rag_search(&self, query: &str, limit: usize) -> Result<Vec<RAGResult>> {
        Ok(vec![])
    }


    // Schema Operations (9 methods)
    pub fn generate_schema_from_description(&self, description: &str) -> Result<String> {
        Err(Error::Generic("Schema generation not yet implemented".to_string()))
    }


    pub fn infer_schema(&self, sample_data: serde_json::Value) -> Result<Schema> {
        Err(Error::Generic("Schema inference not yet implemented".to_string()))
    }


    pub fn infer_schema_from_file(&self, file_path: &str) -> Result<Schema> {
        Err(Error::Generic("File schema inference not yet implemented".to_string()))
    }


    pub fn batch_infer_schema(&self, samples: Vec<serde_json::Value>) -> Result<Vec<Schema>> {
        Ok(vec![])
    }


    pub fn validate_schema(&self, schema: &str) -> Result<bool> {
        Ok(true)
    }


    pub fn compare_schemas(&self, schema1: &str, schema2: &str) -> Result<serde_json::Value> {
        Ok(serde_json::json!({"differences": []}))
    }


    pub fn optimize_schema(&self, table_name: &str) -> Result<String> {
        Ok(String::new())
    }


    pub fn list_schema_templates(&self) -> Result<Vec<SchemaTemplate>> {
        Ok(vec![])
    }


    pub fn instantiate_schema_template(
        &self,
        template_name: &str,
        params: serde_json::Value,
    ) -> Result<String> {
        Err(Error::Generic("Template instantiation not yet implemented".to_string()))
    }


    // Chat Operations (3 methods)
    pub fn list_chat_models(&self) -> Result<Vec<ChatModelInfo>> {
        Ok(vec![])
    }


    pub fn get_chat_model(&self, model_id: &str) -> Result<ChatModelInfo> {
        Err(Error::Generic(format!("Chat model '{}' not found", model_id)))
    }


    pub async fn chat_completion(
        &self,
        model: &str,
        messages: Vec<ChatMessage>,
        stream: bool,
    ) -> Result<ChatCompletionResponse> {
        Err(Error::Generic("Chat completion not yet implemented".to_string()))
    }

Final Verification

Terminal window
# Clean build
cargo clean
cargo build 2>&1 | tee build.log


# Count errors
grep -c "^error" build.log
# Expected: 0


# Count warnings
grep -c "^warning" build.log
# Expected: < 15 (only low-priority lifetime warnings)


# Success message
echo "✅ Build successful! HeliosDB Nano v3.0.0 is ready for GA"

Optional: Fix Warnings (10 minutes)

Remove Unused Imports

File: src/storage/compression/tuple_compression.rs, line 7:

// Before
use crate::{Tuple, Value, Schema, DataType, Result, Error};


// After
use crate::{Tuple, Schema, Result, Error};

File: src/optimizer/rules.rs, line 8:

// Before
use super::cost::{CostEstimator, TableStats, ColumnStats};


// After
use super::cost::{CostEstimator, ColumnStats};

Fix Lifetime Warnings

Add <'_> to 11 locations (see BUILD_FIX_PLAN.md Step 3.2 for details).

Troubleshooting

Issue: “cannot find type VectorStoreInfo”

Solution: Ensure types.rs exports added, lib.rs re-exports updated

Issue: “method create_vector_store has incompatible signature”

Solution: Check handler calling conventions match stub signatures

Issue: Build hangs

Solution: Kill cargo, run cargo clean, retry

Issue: Tests fail

Solution: Expected - stub methods return empty results. Implement logic post-GA.

Next Steps After Build Success

  1. Test API Server: cargo run -- server --port 8080
  2. Test REST Endpoints: Use curl/Postman to verify handlers respond
  3. Update Documentation: OpenAPI spec, README
  4. Tag Release: git tag v3.0.0 && git push --tags
  5. Implement Stubs: Gradually replace stub methods with real logic

Time to Compilation: ~2.5 hours Difficulty: Intermediate Risk: Low (all stubs, no breaking changes)