Dev

python/src/lib.rs

@@ -15,6 +15,7 @@ use ::vectorless::client::{
 };
 use ::vectorless::error::Error as RustError;
 use ::vectorless::metrics::IndexMetrics;
+use ::vectorless::StrategyPreference;
 
 // ============================================================
 // Error Types
@@ -266,6 +267,83 @@ impl PyIndexContext {
     }
 }
 
+// ============================================================
+// StrategyPreference
+// ============================================================
+
+/// Retrieval strategy preference.
+///
+/// Controls how the engine searches the document tree.
+///
+/// ```python
+/// from vectorless import QueryContext, StrategyPreference
+///
+/// # Force keyword-only (fastest, no LLM calls during search)
+/// ctx = QueryContext("revenue").with_doc_id(doc_id).with_strategy(StrategyPreference.KEYWORD)
+///
+/// # Force LLM-guided navigation (most accurate, uses more tokens)
+/// ctx = QueryContext("explain the architecture").with_doc_id(doc_id).with_strategy(StrategyPreference.LLM)
+///
+/// # Force hybrid (BM25 + LLM refinement)
+/// ctx = QueryContext("growth trends").with_doc_id(doc_id).with_strategy(StrategyPreference.HYBRID)
+/// ```
+#[pyclass(name = "StrategyPreference", skip_from_py_object)]
+#[derive(Clone)]
+pub struct PyStrategyPreference {
+    inner: StrategyPreference,
+}
+
+#[pymethods]
+impl PyStrategyPreference {
+    /// Auto-select based on query complexity (default).
+    #[classattr]
+    const AUTO: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::Auto,
+    };
+
+    /// Force keyword-based strategy (fast, no LLM during search).
+    #[classattr]
+    const KEYWORD: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::ForceKeyword,
+    };
+
+    /// Force LLM-guided navigation (deep reasoning).
+    #[classattr]
+    const LLM: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::ForceLlm,
+    };
+
+    /// Force hybrid strategy (BM25 + LLM refinement).
+    #[classattr]
+    const HYBRID: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::ForceHybrid,
+    };
+
+    /// Force cross-document strategy (multi-document retrieval).
+    #[classattr]
+    const CROSS_DOCUMENT: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::ForceCrossDocument,
+    };
+
+    /// Force page-range strategy (filter by page range).
+    #[classattr]
+    const PAGE_RANGE: PyStrategyPreference = PyStrategyPreference {
+        inner: StrategyPreference::ForcePageRange,
+    };
+
+    fn __repr__(&self) -> String {
+        let name = match self.inner {
+            StrategyPreference::Auto => "AUTO",
+            StrategyPreference::ForceKeyword => "KEYWORD",
+            StrategyPreference::ForceLlm => "LLM",
+            StrategyPreference::ForceHybrid => "HYBRID",
+            StrategyPreference::ForceCrossDocument => "CROSS_DOCUMENT",
+            StrategyPreference::ForcePageRange => "PAGE_RANGE",
+        };
+        format!("StrategyPreference.{}", name)
+    }
+}
+
 // ============================================================
 // QueryContext
 // ============================================================
@@ -335,6 +413,15 @@ impl PyQueryContext {
         Self { inner: ctx }
     }
 
+    /// Set the retrieval strategy.
+    ///
+    /// Args:
+    ///     strategy: A StrategyPreference constant, e.g. StrategyPreference.LLM.
+    fn with_strategy(&self, strategy: &PyStrategyPreference) -> Self {
+        let ctx = self.inner.clone().with_strategy(strategy.inner);
+        Self { inner: ctx }
+    }
+
     fn __repr__(&self) -> String {
         "QueryContext(...)".to_string()
     }
@@ -1169,6 +1256,7 @@ fn _vectorless(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<VectorlessError>()?;
     m.add_class::<PyIndexOptions>()?;
     m.add_class::<PyIndexContext>()?;
+    m.add_class::<PyStrategyPreference>()?;
     m.add_class::<PyQueryContext>()?;
     m.add_class::<PyIndexResult>()?;
     m.add_class::<PyIndexItem>()?;

python/vectorless/__init__.py

@@ -26,9 +26,11 @@
     IndexOptions,
     IndexResult,
     IndexItem,
+    IndexMetrics,
     QueryContext,
     QueryResult,
     QueryResultItem,
+    StrategyPreference,
     DocumentInfo,
     DocumentGraph,
     DocumentGraphNode,
@@ -46,9 +48,11 @@
     "IndexOptions",
     "IndexResult",
     "IndexItem",
+    "IndexMetrics",
     "QueryContext",
     "QueryResult",
     "QueryResultItem",
+    "StrategyPreference",
     "DocumentInfo",
     "DocumentGraph",
     "DocumentGraphNode",