Address all open issues (#2-#8): PyO3 bindings, search fix, bi-temporal KG, duplicate detection, CLI improvements

Closes #2 — [PyO3] Expose remaining Rust API methods
  - Added 13 missing methods to Python bindings: deposit_pheromones,
    kg_invalidate, kg_contradictions, kg_add_with_confidence, build_tunnels,
    create_agent, list_agents, diary_write, diary_read, search_by_embedding,
    similarity_edge_count, kg_add_temporal, extract_entities (static)
  - Total PyO3 methods: 21 → 34 (full coverage)

Closes #3 — [PyO3] Add batch mode / deferred save for bulk operations
  - Added auto_save property to Palace class (default True)
  - Set auto_save = False to defer disk writes during bulk operations
  - Call palace.save() manually when ready
  - All mutation methods respect the auto_save flag

Closes #4 — [API] search() always returns error
  - Wrapped embeddings in RefCell<Box<dyn EmbeddingEngine>> for interior mutability
  - search(&self) now works — encodes query via borrow_mut(), no &mut self needed
  - search_mut() deprecated but kept as backward-compatible alias
  - Updated all callers (CLI, benchmarks, tests, PyO3) to use search()

Closes #5 — [PyO3] Expose ONNX embedding engine option
  - Added embedding parameter to Palace constructor ("tfidf" or "onnx")
  - ONNX support requires compile-time feature flag; documented in docstring
  - Groundwork for future ONNX integration from Python

Closes #6 — [KG] Add bi-temporal support to knowledge graph
  - Added StatementType enum: Fact, Observation, Inference, Hypothesis
  - Added invalidated_at field to RelatesTo and Relationship types
  - Added statement_type field with serde(default) for backward compat
  - New kg_add_temporal() method with valid_from, valid_to, statement_type
  - Updated kg_invalidate() to set invalidated_at timestamp + close valid_to
  - Updated kg_query/kg_contradictions to expose all temporal fields
  - Exposed via PyO3, MCP tools, and CLI handlers

Closes #7 — [Feature] Expose duplicate detection via public API and PyO3
  - Added DuplicateMatch struct to gp-palace::search
  - Added check_duplicate() method to GraphPalace API
  - Added add_drawer_if_unique() convenience method
  - Exposed both via PyO3 with configurable threshold

Closes #8 — CLAUDE.md skills file: CLI flag inaccuracies + practical tips
  - Added --description/-d flag to room add CLI command
  - Added add_room_with_description() to palace API (backward compatible)
  - Added --quiet/-q global flag to suppress tunnel build messages
  - Added description parameter to add_room MCP tool schema
  - Added CLI Quick Reference section to skills/graphpalace.md
  - Documented correct flag syntax for all CLI commands

Files changed (15):
  rust/gp-core/src/types.rs          - StatementType enum, RelatesTo temporal fields
  rust/gp-storage/src/memory.rs      - Relationship temporal fields, add_relationship_temporal
  rust/gp-palace/src/palace.rs       - RefCell search fix, check_duplicate, kg_add_temporal, room desc
  rust/gp-palace/src/search.rs       - DuplicateMatch struct
  rust/gp-palace/src/lifecycle.rs    - KgRelationship temporal fields
  rust/gp-palace/src/lib.rs          - Export DuplicateMatch
  rust/gp-python/src/lib.rs          - 13 new methods, batch mode, temporal KG, duplicate detection
  rust/gp-cli/src/main.rs            - --quiet flag, room description, temporal KG handlers
  rust/gp-mcp/src/tools.rs           - add_room description, kg_add temporal params
  rust/gp-bench/*/                   - search_mut → search migration
  rust/gp-palace/tests/              - search_mut → search migration
  skills/graphpalace.md              - CLI Quick Reference, add_room description param

Co-authored-by: web3guru888 <web3guru888@users.noreply.github.com>

Author: web3guru888

rust/gp-bench/benches/palace_benchmarks.rs

@@ -40,7 +40,7 @@ fn search_benchmark(c: &mut Criterion) {
     let mut palace = make_palace(100);
     c.bench_function("search_100_drawers", |b| {
         b.iter(|| {
-            let _ = palace.search_mut(black_box("benchmark drawer content"), 10);
+            let _ = palace.search(black_box("benchmark drawer content"), 10);
         });
     });
 }

rust/gp-bench/src/bin/onnx_eval.rs

@@ -119,7 +119,7 @@ fn run_search_quality(palace: &mut GraphPalace) {
     println!("|---|-------|-------------|---------|-------|-----|-------------|");
 
     for (i, test) in SEARCH_TESTS.iter().enumerate() {
-        let results = palace.search_mut(test.query, 10).unwrap_or_default();
+        let results = palace.search(test.query, 10).unwrap_or_default();
 
         let top1_match = results.first()
             .is_some_and(|r| r.content.contains(test.expected_top));
@@ -163,7 +163,7 @@ fn run_search_quality(palace: &mut GraphPalace) {
     if fail > 0 {
         println!("\n  Failed queries:");
         for (i, test) in SEARCH_TESTS.iter().enumerate() {
-            let results = palace.search_mut(test.query, 3).unwrap_or_default();
+            let results = palace.search(test.query, 3).unwrap_or_default();
             let top1_match = results.first()
                 .is_some_and(|r| r.content.contains(test.expected_top));
             if !top1_match {
@@ -200,7 +200,7 @@ fn run_throughput_benchmarks(palace: &mut GraphPalace) {
     let mut total_us = 0u128;
     for q in &queries {
         let t0 = Instant::now();
-        let _ = palace.search_mut(q, 10);
+        let _ = palace.search(q, 10);
         let elapsed = t0.elapsed();
         total_us += elapsed.as_micros();
         println!("  '{}...' → {:.1}ms", &q[..q.len().min(40)], elapsed.as_secs_f64() * 1000.0);
@@ -260,7 +260,7 @@ fn run_pheromone_test(palace: &mut GraphPalace) {
     println!("╚══════════════════════════════════════════════════════════════╝\n");
 
     // 1. Search for something and deposit pheromones on the path
-    let results = palace.search_mut("pheromone navigation stigmergy", 3).unwrap();
+    let results = palace.search("pheromone navigation stigmergy", 3).unwrap();
     println!("Search for 'pheromone navigation stigmergy':");
     for (i, r) in results.iter().enumerate() {
         println!("  {}: [score={:.4}] {} (id={})", i+1, r.score, &r.content[..r.content.len().min(70)], r.drawer_id);
@@ -291,7 +291,7 @@ fn run_pheromone_test(palace: &mut GraphPalace) {
     }
 
     // 4. Search again — pheromone boost should change ranking
-    let results2 = palace.search_mut("pheromone navigation stigmergy", 3).unwrap();
+    let results2 = palace.search("pheromone navigation stigmergy", 3).unwrap();
     println!("\n### Re-search after pheromone deposit:");
     for (i, r) in results2.iter().enumerate() {
         println!("  {}: [score={:.4}] {} (id={})", i+1, r.score, &r.content[..r.content.len().min(70)], r.drawer_id);
@@ -510,7 +510,7 @@ fn main() {
 
     let mut pass = 0;
     for (query, expected) in &spot_checks {
-        let results = palace.search_mut(query, 1).unwrap();
+        let results = palace.search(query, 1).unwrap();
         let hit = results.first().is_some_and(|r| r.content.contains(expected));
         if hit { pass += 1; }
         let mark = if hit { "PASS" } else { "FAIL" };

rust/gp-bench/src/generators.rs

@@ -386,7 +386,7 @@ mod tests {
     #[test]
     fn generate_palace_tfidf_search_returns_results() {
         let (mut palace, _) = generate_palace_tfidf(1, 2, 5, 0);
-        let results = palace.search_mut("quantum entanglement", 5).unwrap();
+        let results = palace.search("quantum entanglement", 5).unwrap();
         assert!(!results.is_empty(), "TF-IDF search should return results");
     }
 

rust/gp-bench/src/throughput.rs

@@ -104,7 +104,7 @@ pub fn measure_search_throughput(
 
     let t0 = Instant::now();
     for q in &queries {
-        let _ = palace.search_mut(q, 10);
+        let _ = palace.search(q, 10);
     }
     let elapsed_ms = t0.elapsed().as_secs_f64() * 1000.0;
 

rust/gp-cli/src/main.rs

@@ -366,6 +366,37 @@ impl Tunnel {
     }
 }
 
+/// Classification of a knowledge graph statement.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StatementType {
+    /// An established, verified fact.
+    Fact,
+    /// A direct observation (may be noisy or context-dependent).
+    Observation,
+    /// A conclusion derived from other statements.
+    Inference,
+    /// A tentative, unverified proposition.
+    Hypothesis,
+}
+
+impl Default for StatementType {
+    fn default() -> Self {
+        Self::Fact
+    }
+}
+
+impl std::fmt::Display for StatementType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Fact => write!(f, "fact"),
+            Self::Observation => write!(f, "observation"),
+            Self::Inference => write!(f, "inference"),
+            Self::Hypothesis => write!(f, "hypothesis"),
+        }
+    }
+}
+
 /// Entity → Entity knowledge graph relationship.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RelatesTo {
@@ -378,6 +409,12 @@ pub struct RelatesTo {
     pub valid_from: Option<DateTime<Utc>>,
     pub valid_to: Option<DateTime<Utc>>,
     pub observed_at: DateTime<Utc>,
+    /// Timestamp when this triple was retracted/invalidated in the system.
+    #[serde(default)]
+    pub invalidated_at: Option<DateTime<Utc>>,
+    /// Classification of this statement (fact, observation, inference, hypothesis).
+    #[serde(default)]
+    pub statement_type: StatementType,
 }
 
 impl RelatesTo {
@@ -392,6 +429,8 @@ impl RelatesTo {
             valid_from: None,
             valid_to: None,
             observed_at: Utc::now(),
+            invalidated_at: None,
+            statement_type: StatementType::default(),
         }
     }
 }

rust/gp-core/src/types.rs

@@ -102,6 +102,8 @@ pub struct AddRoom {
     pub wing_id: String,
     pub name: String,
     pub hall_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
 }
 
 /// Check whether content is a near-duplicate of an existing drawer.
@@ -124,6 +126,15 @@ pub struct KgAdd {
     pub object: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub confidence: Option<f64>,
+    /// RFC 3339 start of validity window.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub valid_from: Option<String>,
+    /// RFC 3339 end of validity window.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub valid_to: Option<String>,
+    /// Classification: "fact", "observation", "inference", "hypothesis".
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub statement_type: Option<String>,
 }
 
 /// Query triples for an entity, optionally at a point in time.
@@ -325,9 +336,10 @@ pub fn tool_catalog() -> Vec<ToolDefinition> {
             "description" => "string"
         }),
         tool_def!("add_room", "Create a new room in an existing wing.", {
-            "wing_id"   => "string";
-            "name"      => "string";
-            "hall_type" => "string"
+            "wing_id"     => "string";
+            "name"        => "string";
+            "hall_type"   => "string";
+            "description" => "string", optional: true
         }),
         tool_def!("check_duplicate", "Check whether content is a near-duplicate of an existing drawer.", {
             "content"   => "string";
@@ -336,10 +348,13 @@ pub fn tool_catalog() -> Vec<ToolDefinition> {
 
         // ── Knowledge Graph ─────────────────────────────────────────
         tool_def!("kg_add", "Add a (subject, predicate, object) triple to the knowledge graph.", {
-            "subject"    => "string";
-            "predicate"  => "string";
-            "object"     => "string";
-            "confidence" => "number", optional: true
+            "subject"        => "string";
+            "predicate"      => "string";
+            "object"         => "string";
+            "confidence"     => "number", optional: true;
+            "valid_from"     => "string", optional: true;
+            "valid_to"       => "string", optional: true;
+            "statement_type" => "string", optional: true
         }),
         tool_def!("kg_query", "Query triples for an entity, optionally at a point in time.", {
             "entity" => "string";
@@ -552,6 +567,20 @@ mod tests {
             wing_id: "w1".into(),
             name: "Quantum".into(),
             hall_type: "topic".into(),
+            description: None,
+        };
+        let json = serde_json::to_string(&t).unwrap();
+        let back: AddRoom = serde_json::from_str(&json).unwrap();
+        assert_eq!(t, back);
+    }
+
+    #[test]
+    fn add_room_with_description_roundtrip() {
+        let t = AddRoom {
+            wing_id: "w1".into(),
+            name: "Quantum".into(),
+            hall_type: "topic".into(),
+            description: Some("Quantum mechanics research".into()),
         };
         let json = serde_json::to_string(&t).unwrap();
         let back: AddRoom = serde_json::from_str(&json).unwrap();
@@ -575,8 +604,29 @@ mod tests {
             predicate: "discovered".into(),
             object: "relativity".into(),
             confidence: Some(0.99),
+            valid_from: None,
+            valid_to: None,
+            statement_type: None,
+        };
+        let json = serde_json::to_string(&t).unwrap();
+        let back: KgAdd = serde_json::from_str(&json).unwrap();
+        assert_eq!(t, back);
+    }
+
+    #[test]
+    fn kg_add_temporal_roundtrip() {
+        let t = KgAdd {
+            subject: "Earth".into(),
+            predicate: "orbits".into(),
+            object: "Sun".into(),
+            confidence: Some(1.0),
+            valid_from: Some("2026-01-01T00:00:00+00:00".into()),
+            valid_to: None,
+            statement_type: Some("fact".into()),
         };
         let json = serde_json::to_string(&t).unwrap();
+        assert!(json.contains("valid_from"));
+        assert!(json.contains("statement_type"));
         let back: KgAdd = serde_json::from_str(&json).unwrap();
         assert_eq!(t, back);
     }

rust/gp-mcp/src/tools.rs

@@ -15,4 +15,4 @@ pub mod search;
 pub use export::{ImportMode, ImportStats, PalaceExport};
 pub use lifecycle::{ColdSpot, HotPath, KgRelationship, PalaceStatus};
 pub use palace::GraphPalace;
-pub use search::SearchResult;
+pub use search::{DuplicateMatch, SearchResult};

rust/gp-palace/src/lib.rs

@@ -1,6 +1,7 @@
 //! Palace status, hot-path, and cold-spot types.
 
 use chrono::{DateTime, Utc};
+use gp_core::types::StatementType;
 use serde::{Deserialize, Serialize};
 
 /// Snapshot of the palace's current state.
@@ -59,6 +60,21 @@ pub struct KgRelationship {
     pub object: String,
     /// Confidence score in [0, 1].
     pub confidence: f64,
+    /// Start of the assertion validity window.
+    #[serde(default)]
+    pub valid_from: Option<String>,
+    /// End of the assertion validity window.
+    #[serde(default)]
+    pub valid_to: Option<String>,
+    /// When the triple was first recorded.
+    #[serde(default)]
+    pub observed_at: Option<String>,
+    /// When the triple was retracted/invalidated in the system.
+    #[serde(default)]
+    pub invalidated_at: Option<String>,
+    /// Classification: fact, observation, inference, hypothesis.
+    #[serde(default)]
+    pub statement_type: StatementType,
 }
 
 #[cfg(test)]
@@ -134,10 +150,48 @@ mod tests {
             predicate: "discovered".into(),
             object: "Relativity".into(),
             confidence: 0.99,
+            valid_from: None,
+            valid_to: None,
+            observed_at: Some("2026-01-01T00:00:00+00:00".into()),
+            invalidated_at: None,
+            statement_type: StatementType::Fact,
         };
         let json = serde_json::to_string(&rel).unwrap();
         let deser: KgRelationship = serde_json::from_str(&json).unwrap();
         assert_eq!(deser.predicate, "discovered");
         assert!((deser.confidence - 0.99).abs() < 1e-10);
+        assert_eq!(deser.statement_type, StatementType::Fact);
+        assert!(deser.invalidated_at.is_none());
+    }
+
+    #[test]
+    fn kg_relationship_backward_compat_deserialization() {
+        // Old JSON without temporal fields should still deserialize (serde defaults).
+        let json = r#"{"subject":"A","predicate":"knows","object":"B","confidence":0.5}"#;
+        let deser: KgRelationship = serde_json::from_str(json).unwrap();
+        assert_eq!(deser.subject, "A");
+        assert_eq!(deser.statement_type, StatementType::Fact);
+        assert!(deser.valid_from.is_none());
+        assert!(deser.invalidated_at.is_none());
+    }
+
+    #[test]
+    fn kg_relationship_hypothesis_round_trip() {
+        let rel = KgRelationship {
+            subject: "X".into(),
+            predicate: "causes".into(),
+            object: "Y".into(),
+            confidence: 0.3,
+            valid_from: Some("2026-01-01T00:00:00+00:00".into()),
+            valid_to: Some("2026-12-31T23:59:59+00:00".into()),
+            observed_at: Some("2026-04-14T00:00:00+00:00".into()),
+            invalidated_at: None,
+            statement_type: StatementType::Hypothesis,
+        };
+        let json = serde_json::to_string(&rel).unwrap();
+        assert!(json.contains("hypothesis"));
+        let deser: KgRelationship = serde_json::from_str(&json).unwrap();
+        assert_eq!(deser.statement_type, StatementType::Hypothesis);
+        assert!(deser.valid_from.is_some());
     }
 }