lance-context 0.3.3__tar.gz → 0.4.1__tar.gz

{lance_context-0.3.3 → lance_context-0.4.1}/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/lance-context-core", "crates/lance-context-api", "python"]
+members = ["crates/lance-context-core", "crates/lance-context-api", "crates/lance-context-client", "python"]
 resolver = "2"
 
 [workspace.package]

{lance_context-0.3.3 → lance_context-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lance-context
-Version: 0.3.3
+Version: 0.4.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
@@ -8,10 +8,9 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Scientific/Engineering
 Requires-Dist: pyarrow>=14
@@ -21,6 +20,8 @@ Requires-Dist: lance-graph==0.5.4 ; extra == 'graph'
 Requires-Dist: pylance>=7.0.0,<8 ; extra == 'lance-python'
 Requires-Dist: lance-namespace>=0.7.7,<0.8 ; extra == 'lance-python'
 Requires-Dist: lancedb==0.27.1 ; extra == 'lance-python'
+Requires-Dist: openai>=1.0 ; extra == 'openai'
+Requires-Dist: sentence-transformers>=2.0 ; extra == 'sentence-transformers'
 Requires-Dist: pytest ; extra == 'tests'
 Requires-Dist: pytest-asyncio ; extra == 'tests'
 Requires-Dist: ruff ; extra == 'tests'
@@ -33,6 +34,8 @@ Requires-Dist: lancedb==0.27.1 ; extra == 'tests'
 Provides-Extra: dev
 Provides-Extra: graph
 Provides-Extra: lance-python
+Provides-Extra: openai
+Provides-Extra: sentence-transformers
 Provides-Extra: tests
 License-File: LICENSE
 Summary: Multimodal, versioned context storage for agentic workflows

{lance_context-0.3.3 → lance_context-0.4.1}/crates/lance-context-api/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lance-context-api"
-version = "0.2.4"
+version = "0.4.1"
 edition = "2021"
 license = "Apache-2.0"
 authors = ["Lance Devs <dev@lancedb.com>"]

{lance_context-0.3.3 → lance_context-0.4.1}/crates/lance-context-api/src/lib.rs

@@ -34,20 +34,61 @@ pub trait ContextStoreApi {
         records: &[AddRecordRequest],
     ) -> impl Future<Output = ContextResult<AddRecordsResponse>> + Send;
 
+    fn upsert(
+        &mut self,
+        request: &UpsertRecordRequest,
+    ) -> impl Future<Output = ContextResult<UpsertRecordResponse>> + Send;
+
+    fn update(
+        &mut self,
+        request: &UpdateRecordRequest,
+    ) -> impl Future<Output = ContextResult<UpdateRecordResponse>> + Send;
+
     fn get(&self, id: &str) -> impl Future<Output = ContextResult<Option<RecordDto>>> + Send;
 
+    fn get_by_external_id(
+        &self,
+        external_id: &str,
+    ) -> impl Future<Output = ContextResult<Option<RecordDto>>> + Send;
+
+    fn delete_by_id(
+        &mut self,
+        id: &str,
+    ) -> impl Future<Output = ContextResult<DeleteRecordResponse>> + Send;
+
+    fn delete_by_external_id(
+        &mut self,
+        external_id: &str,
+    ) -> impl Future<Output = ContextResult<DeleteRecordResponse>> + Send;
+
     fn list(
         &self,
         limit: Option<usize>,
         offset: Option<usize>,
+        filters: Option<Value>,
+        include_expired: bool,
+        include_retired: bool,
     ) -> impl Future<Output = ContextResult<Vec<RecordDto>>> + Send;
 
-    fn search(
+    fn related(
         &self,
-        query: &[f32],
+        target_id: &str,
+        relation: Option<&str>,
         limit: Option<usize>,
+        include_expired: bool,
+        include_retired: bool,
+    ) -> impl Future<Output = ContextResult<Vec<RecordDto>>> + Send;
+
+    fn search(
+        &self,
+        request: &SearchRequest,
     ) -> impl Future<Output = ContextResult<Vec<SearchResultDto>>> + Send;
 
+    fn retrieve(
+        &self,
+        request: &RetrieveRequest,
+    ) -> impl Future<Output = ContextResult<Vec<RetrieveResultDto>>> + Send;
+
     fn version(&self) -> u64;
 
     fn checkout(&mut self, version: u64) -> impl Future<Output = ContextResult<()>> + Send;
@@ -73,6 +114,10 @@ pub struct CreateContextRequest {
     pub id_index_type: Option<String>,
     #[serde(default)]
     pub blob_columns: Option<Vec<String>>,
+    #[serde(default)]
+    pub embedding_dim: Option<i32>,
+    #[serde(default)]
+    pub distance_metric: Option<String>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
@@ -103,6 +148,14 @@ pub struct StateMetadataDto {
     pub custom: Option<String>,
 }
 
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct RelationshipDto {
+    pub target_id: String,
+    pub relation: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub weight: Option<f32>,
+}
+
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct AddRecordRequest {
     #[serde(default = "default_role")]
@@ -125,11 +178,17 @@ pub struct AddRecordRequest {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub session_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tenant: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub external_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub state_metadata: Option<StateMetadataDto>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub metadata: Option<Value>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub relationships: Vec<RelationshipDto>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub expires_at: Option<DateTime<Utc>>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -150,6 +209,91 @@ pub struct AddRecordsResponse {
     pub count: usize,
 }
 
+#[derive(Debug, Serialize, Deserialize)]
+pub struct UpsertRecordRequest {
+    pub record: AddRecordRequest,
+    #[serde(default = "default_upsert_key")]
+    pub key: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct UpsertRecordResponse {
+    pub version: u64,
+    pub inserted: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub replaced_id: Option<String>,
+    pub record: RecordDto,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct RecordPatchDto {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bot_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tenant: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_metadata: Option<StateMetadataDto>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub relationships: Option<Vec<RelationshipDto>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expires_at: Option<DateTime<Utc>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub retention_policy: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub lifecycle_status: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub retired_at: Option<DateTime<Utc>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub retired_reason: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub embedding: Option<Vec<f32>>,
+}
+
+impl RecordPatchDto {
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.bot_id.is_none()
+            && self.session_id.is_none()
+            && self.tenant.is_none()
+            && self.source.is_none()
+            && self.state_metadata.is_none()
+            && self.metadata.is_none()
+            && self.relationships.is_none()
+            && self.expires_at.is_none()
+            && self.retention_policy.is_none()
+            && self.lifecycle_status.is_none()
+            && self.retired_at.is_none()
+            && self.retired_reason.is_none()
+            && self.embedding.is_none()
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct UpdateRecordRequest {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub external_id: Option<String>,
+    #[serde(default)]
+    pub patch: RecordPatchDto,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct UpdateRecordResponse {
+    pub version: u64,
+    pub updated: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub replaced_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub record: Option<RecordDto>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RecordDto {
     pub id: String,
@@ -160,6 +304,10 @@ pub struct RecordDto {
     pub bot_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub session_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tenant: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
     pub created_at: DateTime<Utc>,
     pub role: String,
     pub content_type: String,
@@ -178,6 +326,8 @@ pub struct RecordDto {
     pub state_metadata: Option<StateMetadataDto>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub metadata: Option<Value>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub relationships: Vec<RelationshipDto>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub expires_at: Option<DateTime<Utc>>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -207,6 +357,12 @@ pub struct GetRecordResponse {
     pub record: Option<RecordDto>,
 }
 
+#[derive(Debug, Serialize, Deserialize)]
+pub struct DeleteRecordResponse {
+    pub deleted: bool,
+    pub version: u64,
+}
+
 // ---------------------------------------------------------------------------
 // Search
 // ---------------------------------------------------------------------------
@@ -216,6 +372,14 @@ pub struct SearchRequest {
     pub query: Vec<f32>,
     #[serde(default = "default_search_limit")]
     pub limit: usize,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub filters: Option<Value>,
+    #[serde(default)]
+    pub include_expired: bool,
+    #[serde(default)]
+    pub include_retired: bool,
+    #[serde(default)]
+    pub include_relationships: bool,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
@@ -229,6 +393,47 @@ pub struct SearchResponse {
     pub results: Vec<SearchResultDto>,
 }
 
+// ---------------------------------------------------------------------------
+// Hybrid retrieval
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct RetrieveRequest {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub vector: Option<Vec<f32>>,
+    #[serde(default = "default_search_limit")]
+    pub limit: usize,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub filters: Option<Value>,
+    #[serde(default)]
+    pub include_expired: bool,
+    #[serde(default)]
+    pub include_retired: bool,
+    #[serde(default)]
+    pub include_relationships: bool,
+    #[serde(default = "default_retrieve_fusion")]
+    pub fusion: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct RetrieveResultDto {
+    pub record: RecordDto,
+    pub score: f32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub vector_distance: Option<f32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text_score: Option<f32>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub matched_channels: Vec<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct RetrieveResponse {
+    pub results: Vec<RetrieveResultDto>,
+}
+
 // ---------------------------------------------------------------------------
 // Versioning
 // ---------------------------------------------------------------------------
@@ -301,10 +506,18 @@ fn default_role() -> String {
     "user".to_string()
 }
 
+fn default_upsert_key() -> String {
+    "external_id".to_string()
+}
+
 fn default_search_limit() -> usize {
     10
 }
 
+fn default_retrieve_fusion() -> String {
+    "rrf".to_string()
+}
+
 fn serialize_base64_opt<S>(data: &Option<Vec<u8>>, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: serde::Serializer,
@@ -328,3 +541,38 @@ where
         None => Ok(None),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn search_request_legacy_payload_defaults_filters_and_lifecycle() {
+        // Clients written against the pre-#89 shape send only query/limit.
+        let req: SearchRequest =
+            serde_json::from_str(r#"{"query": [0.1, 0.2], "limit": 5}"#).unwrap();
+        assert_eq!(req.query, vec![0.1, 0.2]);
+        assert_eq!(req.limit, 5);
+        assert!(req.filters.is_none());
+        assert!(!req.include_expired);
+        assert!(!req.include_retired);
+        assert!(!req.include_relationships);
+    }
+
+    #[test]
+    fn search_request_defaults_limit_when_omitted() {
+        let req: SearchRequest = serde_json::from_str(r#"{"query": [1.0]}"#).unwrap();
+        assert_eq!(req.limit, default_search_limit());
+    }
+
+    #[test]
+    fn search_request_parses_filters_and_lifecycle() {
+        let req: SearchRequest = serde_json::from_str(
+            r#"{"query": [1.0], "filters": {"tenant": "acme"}, "include_expired": true, "include_retired": true}"#,
+        )
+        .unwrap();
+        assert_eq!(req.filters, Some(serde_json::json!({"tenant": "acme"})));
+        assert!(req.include_expired);
+        assert!(req.include_retired);
+    }
+}

lance_context-0.4.1/crates/lance-context-client/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "lance-context-client"
+version = "0.4.1"
+edition = "2021"
+license = "Apache-2.0"
+authors = ["Lance Devs <dev@lancedb.com>"]
+repository = "https://github.com/lancedb/lance-context"
+description = "Rust client for the lance-context REST API"
+keywords = ["context", "lance", "client", "api"]
+
+[dependencies]
+lance-context-api = { version = "0.4.1", path = "../lance-context-api" }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"

lance_context-0.4.1/crates/lance-context-client/src/error.rs

@@ -0,0 +1,12 @@
+#[derive(Debug, thiserror::Error)]
+pub enum ClientError {
+    #[error("HTTP error: {0}")]
+    Http(#[from] reqwest::Error),
+
+    #[error("API error ({status}): [{code}] {message}")]
+    Api {
+        status: u16,
+        code: String,
+        message: String,
+    },
+}