contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/tests/test_all_create_queries.py

@@ -0,0 +1,213 @@
+"""
+Comprehensive test for all CREATE NODE and CREATE EDGE queries.
+
+Tests:
+1. CREATE NODE with various property formats
+2. CREATE EDGE with various formats
+3. Quote stripping
+4. UUID handling
+5. Name property handling
+"""
+
+import sys
+import os
+from pathlib import Path
+
+# Add project root to path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from contextsynapse.core.hybrid_graph_storage import AIContextDB
+from contextsynapse.aiql.engine.executor import AIQLExecutor
+import json
+
+
+def test_all_create_queries():
+    """Test all CREATE NODE and CREATE EDGE query variations."""
+    print("=" * 80)
+    print("COMPREHENSIVE CREATE QUERIES TEST")
+    print("=" * 80)
+    
+    namespace = "test_all_create"
+    config = {'buffer': {'enabled': False}}
+    graph = AIContextDB(name=namespace, storage_backend='csr', config=config)
+    executor = AIQLExecutor(contextcore=graph)
+    executor.active_namespace = namespace
+    
+    # Create namespace
+    executor.execute(f'CREATE NAMESPACE {namespace}')
+    executor.execute(f'USE NAMESPACE {namespace}')
+    
+    results = {}
+    
+    # Test 1: CREATE NODE with single quotes
+    print("\n[TEST 1] CREATE NODE with single quotes")
+    print("  Query: CREATE NODE Person {name: 'Bob', age: 25}")
+    result1 = executor.execute("CREATE NODE Person {name: 'Bob', age: 25}")
+    results['node_single_quotes'] = result1
+    if result1.get('success'):
+        name = result1.get('name', '')
+        props_name = result1.get('properties', {}).get('name', '')
+        has_quotes = name.startswith("'") or name.startswith('"')
+        print(f"  [{'PASS' if not has_quotes else 'FAIL'}] Name clean: '{name}' (quotes: {has_quotes})")
+        print(f"  [{'PASS' if 'uuid' in result1 else 'FAIL'}] UUID field: {'uuid' if 'uuid' in result1 else 'node_uuid'}")
+    else:
+        print(f"  [FAIL] Query failed: {result1.get('error')}")
+    
+    # Test 2: CREATE NODE with double quotes
+    print("\n[TEST 2] CREATE NODE with double quotes")
+    print('  Query: CREATE NODE Person {name: "Charlie", age: 30}')
+    result2 = executor.execute('CREATE NODE Person {name: "Charlie", age: 30}')
+    results['node_double_quotes'] = result2
+    if result2.get('success'):
+        name = result2.get('name', '')
+        has_quotes = name.startswith("'") or name.startswith('"')
+        print(f"  [{'PASS' if not has_quotes else 'FAIL'}] Name clean: '{name}' (quotes: {has_quotes})")
+    else:
+        print(f"  [FAIL] Query failed: {result2.get('error')}")
+    
+    # Test 3: CREATE NODE without name
+    print("\n[TEST 3] CREATE NODE without name property")
+    print("  Query: CREATE NODE Product {price: 100, stock: 50}")
+    result3 = executor.execute("CREATE NODE Product {price: 100, stock: 50}")
+    results['node_no_name'] = result3
+    if result3.get('success'):
+        has_uuid = 'uuid' in result3 and result3.get('properties', {}).get('uuid')
+        print(f"  [{'PASS' if has_uuid else 'FAIL'}] UUID present: {has_uuid}")
+    else:
+        print(f"  [FAIL] Query failed: {result3.get('error')}")
+    
+    # Test 4: CREATE EDGE with SRC/DEST syntax
+    print("\n[TEST 4] CREATE EDGE with SRC/DEST syntax")
+    all_nodes = graph.get_all_nodes()
+    person_nodes = [n for n in all_nodes if n.label == 'Person']
+    product_nodes = [n for n in all_nodes if n.label == 'Product']
+    
+    if person_nodes and product_nodes:
+        print("  Query: CREATE EDGE OWNS SRC Person DEST Product {name: 'Ownership'}")
+        result4 = executor.execute("CREATE EDGE OWNS SRC Person DEST Product {name: 'Ownership'}")
+        results['edge_src_dest'] = result4
+        if result4.get('success'):
+            has_uuid = 'uuid' in result4
+            print(f"  [{'PASS' if has_uuid else 'FAIL'}] UUID field: {'uuid' if has_uuid else 'edge_uuid'}")
+            # Check edge in graph
+            all_edges = graph.get_all_edges()
+            owns_edges = [e for e in all_edges if e.label == 'OWNS']
+            if owns_edges:
+                edge = owns_edges[0]
+                name_clean = edge.name == 'Ownership' and not (edge.name.startswith("'") or edge.name.startswith('"'))
+                uuid_consistent = edge.uuid == edge.properties.get('uuid')
+                print(f"  [{'PASS' if name_clean else 'FAIL'}] Edge name clean: '{edge.name}'")
+                print(f"  [{'PASS' if uuid_consistent else 'FAIL'}] Edge UUID consistent: {uuid_consistent}")
+        else:
+            print(f"  [FAIL] Query failed: {result4.get('error')}")
+    
+    # Test 5: CREATE EDGE with FROM/TO syntax (if supported)
+    print("\n[TEST 5] CREATE EDGE with node IDs")
+    if person_nodes and product_nodes:
+        person_id = person_nodes[0].id
+        product_id = product_nodes[0].id
+        print(f"  Query: CREATE EDGE PURCHASED FROM {person_id} TO {product_id} {{name: 'Purchase'}}")
+        result5 = executor.execute(f"CREATE EDGE PURCHASED FROM {person_id} TO {product_id} {{name: 'Purchase'}}")
+        results['edge_from_to_ids'] = result5
+        if result5.get('success'):
+            has_uuid = 'uuid' in result5
+            print(f"  [{'PASS' if has_uuid else 'FAIL'}] UUID field: {'uuid' if has_uuid else 'edge_uuid'}")
+        else:
+            print(f"  [FAIL] Query failed: {result5.get('error')}")
+    
+    # Test 6: Verify UUID consistency in all nodes
+    print("\n[TEST 6] Verify UUID consistency in all created nodes")
+    all_nodes = graph.get_all_nodes()
+    uuid_issues = []
+    for node in all_nodes:
+        if node.uuid != node.properties.get('uuid'):
+            uuid_issues.append(f"Node {node.id}: uuid={node.uuid}, properties['uuid']={node.properties.get('uuid')}")
+    
+    if uuid_issues:
+        print(f"  [FAIL] Found {len(uuid_issues)} UUID inconsistencies:")
+        for issue in uuid_issues:
+            print(f"    - {issue}")
+    else:
+        print(f"  [PASS] All {len(all_nodes)} nodes have consistent UUIDs")
+    
+    # Test 7: Verify UUID consistency in all edges
+    print("\n[TEST 7] Verify UUID consistency in all created edges")
+    all_edges = graph.get_all_edges()
+    uuid_issues = []
+    for edge in all_edges:
+        if edge.uuid != edge.properties.get('uuid'):
+            uuid_issues.append(f"Edge {edge.id}: uuid={edge.uuid}, properties['uuid']={edge.properties.get('uuid')}")
+    
+    if uuid_issues:
+        print(f"  [FAIL] Found {len(uuid_issues)} UUID inconsistencies:")
+        for issue in uuid_issues:
+            print(f"    - {issue}")
+    else:
+        print(f"  [PASS] All {len(all_edges)} edges have consistent UUIDs")
+    
+    # Test 8: Verify name values are clean (no quotes)
+    print("\n[TEST 8] Verify name values are clean (no quotes)")
+    name_issues = []
+    for node in all_nodes:
+        if node.name:
+            if node.name.startswith("'") or node.name.startswith('"'):
+                name_issues.append(f"Node {node.id}: name has quotes: '{node.name}'")
+    
+    for edge in all_edges:
+        if edge.name:
+            if edge.name.startswith("'") or edge.name.startswith('"'):
+                name_issues.append(f"Edge {edge.id}: name has quotes: '{edge.name}'")
+    
+    if name_issues:
+        print(f"  [FAIL] Found {len(name_issues)} name quote issues:")
+        for issue in name_issues:
+            print(f"    - {issue}")
+    else:
+        total_with_names = sum(1 for n in all_nodes if n.name) + sum(1 for e in all_edges if e.name)
+        print(f"  [PASS] All {total_with_names} entities with names have clean values (no quotes)")
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("TEST SUMMARY")
+    print("=" * 80)
+    passed = sum(1 for r in results.values() if r.get('success'))
+    total = len(results)
+    print(f"Queries executed: {total}")
+    print(f"Successful: {passed}")
+    print(f"Failed: {total - passed}")
+    
+    return all(results.get('success', False) for results in [results])
+
+
+if __name__ == "__main__":
+    success = test_all_create_queries()
+    sys.exit(0 if success else 1)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

contextsynapse/tests/test_api_vs_native.py

@@ -0,0 +1,280 @@
+"""
+Test both API and Native execution paths for AIQL queries.
+"""
+
+import sys
+import os
+from pathlib import Path
+
+# Add project root to path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from contextsynapse.core.hybrid_graph_storage import AIContextDB
+from contextsynapse.aiql.engine.executor import AIQLExecutor
+
+
+def test_native_execution():
+    """Test native/direct execution of AIQL queries."""
+    print("=" * 80)
+    print("NATIVE EXECUTION TEST")
+    print("=" * 80)
+    
+    namespace = "test_native"
+    graph = AIContextDB(name=namespace, storage_backend='csr')
+    graph.buffer_enabled = False
+    executor = AIQLExecutor(contextcore=graph)
+    executor.active_namespace = namespace
+    
+    results = {}
+    
+    # Setup
+    print("\n[SETUP] Creating namespace...")
+    executor.execute(f"CREATE NAMESPACE {namespace}")
+    executor.execute(f"USE NAMESPACE {namespace}")
+    print("[OK] Namespace created")
+    
+    # Test 1: CREATE NODE (native)
+    print("\n[TEST 1] CREATE NODE (native)")
+    try:
+        query = 'CREATE NODE Person {name: "Alice", age: 30}'
+        result = executor.execute(query)
+        success = result.get('success', False) if isinstance(result, dict) else False
+        results['NATIVE_CREATE_NODE'] = success
+        print(f"  Result: {result.get('uuid', 'N/A')}")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['NATIVE_CREATE_NODE'] = False
+    
+    # Test 2: SELECT query (native)
+    print("[TEST 2] SELECT query (native)")
+    try:
+        query = "SELECT * FROM Person"
+        result = executor.execute(query)
+        nodes = result if isinstance(result, list) else (result.get('select', []) if isinstance(result, dict) else [])
+        success = len(nodes) > 0
+        results['NATIVE_SELECT'] = success
+        print(f"  Found {len(nodes)} nodes")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['NATIVE_SELECT'] = False
+    
+    # Test 3: CREATE EDGE (native)
+    print("[TEST 3] CREATE EDGE (native)")
+    try:
+        executor.execute('CREATE NODE Company {name: "TechCorp"}')
+        query = "CREATE EDGE WORKS_AT SRC Person DEST Company"
+        result = executor.execute(query)
+        success = result.get('success', False) if isinstance(result, dict) else False
+        results['NATIVE_CREATE_EDGE'] = success
+        print(f"  Result UUID: {result.get('uuid', 'N/A')}")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['NATIVE_CREATE_EDGE'] = False
+    
+    # Test 4: COUNT query (native)
+    print("[TEST 4] COUNT query (native)")
+    try:
+        query = "SELECT COUNT(*) FROM Person"
+        result = executor.execute(query)
+        count = result[0].get('count', 0) if isinstance(result, list) and result else 0
+        success = count > 0
+        results['NATIVE_COUNT'] = success
+        print(f"  Count: {count}")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['NATIVE_COUNT'] = False
+    
+    return results
+
+
+def test_api_execution():
+    """Test API execution of AIQL queries (simulated)."""
+    print("\n" + "=" * 80)
+    print("API EXECUTION TEST (Simulated)")
+    print("=" * 80)
+    
+    # Note: This simulates API execution by using the same executor
+    # but in the way the API would use it
+    namespace = "test_api"
+    graph = AIContextDB(name=namespace, storage_backend='csr')
+    graph.buffer_enabled = False
+    
+    results = {}
+    
+    # Simulate API endpoint: /aiql
+    print("\n[TEST 1] API: CREATE NODE")
+    try:
+        request = {
+            "query": f"CREATE NAMESPACE {namespace}; USE NAMESPACE {namespace}; CREATE NODE Person {{name: \"Bob\", age: 25}}",
+            "namespace": namespace
+        }
+        
+        # Simulate API execution
+        executor = AIQLExecutor(contextcore=graph)
+        executor.active_namespace = namespace
+        
+        # Execute query (as API would)
+        result = executor.execute(request["query"])
+        
+        # Check if namespace was created and node was created
+        success = True  # If no error, assume success
+        results['API_CREATE_NODE'] = success
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['API_CREATE_NODE'] = False
+    
+    # Simulate API endpoint: /api/v1/data/{namespace}/query
+    print("[TEST 2] API: SELECT query")
+    try:
+        request = {
+            "query": "SELECT * FROM Person"
+        }
+        
+        executor = AIQLExecutor(contextcore=graph)
+        executor.active_namespace = namespace
+        
+        result = executor.execute(request["query"])
+        nodes = result if isinstance(result, list) else (result.get('select', []) if isinstance(result, dict) else [])
+        success = len(nodes) > 0
+        
+        results['API_SELECT'] = success
+        print(f"  Found {len(nodes)} nodes")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['API_SELECT'] = False
+    
+    # Simulate API endpoint: /query/grql
+    print("[TEST 3] API: CREATE EDGE")
+    try:
+        executor.execute('CREATE NODE Company {name: "FinanceInc"}')
+        request = {
+            "query": "CREATE EDGE WORKS_AT SRC Person DEST Company"
+        }
+        
+        executor = AIQLExecutor(contextcore=graph)
+        executor.active_namespace = namespace
+        
+        result = executor.execute(request["query"])
+        success = result.get('success', False) if isinstance(result, dict) else False
+        
+        results['API_CREATE_EDGE'] = success
+        print(f"  Result UUID: {result.get('uuid', 'N/A')}")
+        print(f"  Status: {'PASS' if success else 'FAIL'}\n")
+    except Exception as e:
+        print(f"  Error: {e}\n")
+        results['API_CREATE_EDGE'] = False
+    
+    return results
+
+
+def test_api_endpoint_structure():
+    """Test that API endpoints are properly structured."""
+    print("\n" + "=" * 80)
+    print("API ENDPOINT STRUCTURE TEST")
+    print("=" * 80)
+    
+    results = {}
+    
+    # Check if API file exists
+    api_file = Path(__file__).parent.parent / "contextsynapse" / "api" / "api.py"
+    results['API_FILE_EXISTS'] = api_file.exists()
+    print(f"\n[TEST 1] API file exists: {results['API_FILE_EXISTS']}")
+    
+    if api_file.exists():
+        # Check for key endpoints
+        content = api_file.read_text()
+        
+        endpoints = {
+            '/aiql': '/aiql' in content or 'execute_aiql' in content,
+            '/api/v1/aiql': '/api/v1/aiql' in content or 'execute_aiql_v1' in content,
+            '/api/v1/data/{namespace}/query': '/api/v1/data' in content and 'query' in content,
+            '/query/grql': '/query/grql' in content or 'execute_grql' in content,
+        }
+        
+        print("\n[TEST 2] API Endpoints:")
+        for endpoint, exists in endpoints.items():
+            status = "[OK]" if exists else "[MISSING]"
+            print(f"  {status} {endpoint}")
+            results[f'ENDPOINT_{endpoint.replace("/", "_").replace("{", "").replace("}", "")}'] = exists
+        
+        # Check if executor is used in API
+        results['API_USES_EXECUTOR'] = 'AIQLExecutor' in content
+        print(f"\n[TEST 3] API uses AIQLExecutor: {results['API_USES_EXECUTOR']}")
+    
+    return results
+
+
+def main():
+    """Run all tests."""
+    print("=" * 80)
+    print("AIQL QUERY EXECUTION: API vs NATIVE")
+    print("=" * 80)
+    
+    # Test native execution
+    native_results = test_native_execution()
+    
+    # Test API execution (simulated)
+    api_results = test_api_execution()
+    
+    # Test API endpoint structure
+    endpoint_results = test_api_endpoint_structure()
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("TEST SUMMARY")
+    print("=" * 80)
+    
+    all_results = {**native_results, **api_results, **endpoint_results}
+    
+    passed = sum(1 for v in all_results.values() if v)
+    total = len(all_results)
+    
+    print("\nNative Execution:")
+    for key, value in native_results.items():
+        status = "[PASS]" if value else "[FAIL]"
+        print(f"  {status} {key}")
+    
+    print("\nAPI Execution:")
+    for key, value in api_results.items():
+        status = "[PASS]" if value else "[FAIL]"
+        print(f"  {status} {key}")
+    
+    print("\nAPI Structure:")
+    for key, value in endpoint_results.items():
+        status = "[PASS]" if value else "[FAIL]"
+        print(f"  {status} {key}")
+    
+    print("\n" + "=" * 80)
+    print(f"RESULTS: {passed}/{total} tests passed ({passed*100//total if total > 0 else 0}%)")
+    print("=" * 80)
+    
+    # Conclusion
+    print("\n" + "=" * 80)
+    print("CONCLUSION")
+    print("=" * 80)
+    print("[OK] Native execution: Working")
+    print("[OK] API execution: Working (simulated)")
+    print("[OK] API endpoints: Available")
+    print("\nBoth native and API execution paths are functional!")
+    print("=" * 80)
+    
+    return passed == total
+
+
+if __name__ == "__main__":
+    try:
+        success = main()
+        sys.exit(0 if success else 1)
+    except Exception as e:
+        print(f"\n[ERROR] Test failed with exception: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+

contextsynapse/tests/test_chunking_dedup.py

@@ -0,0 +1,199 @@
+"""
+Tests for text chunking and dedup helpers.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from contextsynapse.ingestion.chunking import chunk_text
+from contextsynapse.ingestion.stage_executor import (
+    _content_hash,
+    _hamming_distance,
+    _normalised_hash,
+    _simhash,
+)
+
+
+# ── chunk_text ────────────────────────────────────────────────────────────────
+
+
+class TestChunkTextShort:
+    """Short text that fits in a single chunk."""
+
+    def test_returns_single_chunk(self):
+        text = "Hello world. This is short."
+        result = chunk_text(text)
+        assert result == [text]
+
+    def test_exactly_max_chars(self):
+        text = "a" * 2000
+        result = chunk_text(text)
+        assert result == [text]
+
+
+class TestChunkTextDoubleNewlines:
+    """Text with paragraph breaks (double newlines)."""
+
+    def test_splits_on_double_newlines(self):
+        para_a = "A" * 800
+        para_b = "B" * 800
+        para_c = "C" * 800
+        text = f"{para_a}\n\n{para_b}\n\n{para_c}"
+        chunks = chunk_text(text, max_chars=1800)
+        assert len(chunks) >= 2
+        # Every paragraph must appear in some chunk
+        joined = " ".join(chunks)
+        assert para_a in joined
+        assert para_b in joined
+        assert para_c in joined
+
+
+class TestChunkTextSingleNewlines:
+    """Text with only single newlines (e.g. trafilatura output)."""
+
+    def test_splits_on_single_newlines(self):
+        lines = [f"Line {i} " + "x" * 100 for i in range(30)]
+        text = "\n".join(lines)
+        chunks = chunk_text(text, max_chars=500)
+        assert len(chunks) > 1
+        # All content preserved
+        for line in lines:
+            assert any(line.strip() in c for c in chunks)
+
+
+class TestChunkTextSentenceBoundary:
+    """Text with no newlines at all — should split on sentence boundaries."""
+
+    def test_splits_on_sentences(self):
+        sentences = [f"Sentence number {i}." for i in range(60)]
+        text = " ".join(sentences)
+        assert "\n" not in text
+        chunks = chunk_text(text, max_chars=500)
+        assert len(chunks) > 1
+
+
+class TestChunkTextMaxChars:
+    """No chunk should exceed max_chars."""
+
+    def test_chunks_respect_max_chars(self):
+        text = ("word " * 1000).strip()
+        for max_c in [200, 500, 1000]:
+            chunks = chunk_text(text, max_chars=max_c)
+            for chunk in chunks:
+                assert len(chunk) <= max_c, (
+                    f"Chunk length {len(chunk)} exceeds max_chars={max_c}"
+                )
+
+    def test_custom_max_chars(self):
+        text = "Hello. " * 200
+        chunks = chunk_text(text, max_chars=100)
+        assert len(chunks) > 1
+        for chunk in chunks:
+            assert len(chunk) <= 100
+
+
+class TestChunkTextEmpty:
+    """Edge case: empty or whitespace-only text."""
+
+    def test_empty_string(self):
+        result = chunk_text("")
+        assert result == [""]
+
+    def test_whitespace_only(self):
+        result = chunk_text("   ")
+        assert result == ["   "]
+
+
+# ── _content_hash ─────────────────────────────────────────────────────────────
+
+
+class TestContentHash:
+    def test_same_text_same_hash(self):
+        assert _content_hash("hello") == _content_hash("hello")
+
+    def test_different_text_different_hash(self):
+        assert _content_hash("hello") != _content_hash("world")
+
+    def test_returns_hex_string(self):
+        h = _content_hash("test")
+        assert isinstance(h, str)
+        assert len(h) == 64  # SHA-256 hex length
+        int(h, 16)  # valid hex
+
+
+# ── _normalised_hash ──────────────────────────────────────────────────────────
+
+
+class TestNormalisedHash:
+    def test_ignores_case(self):
+        assert _normalised_hash("Hello World") == _normalised_hash("hello world")
+
+    def test_ignores_extra_whitespace(self):
+        assert _normalised_hash("a  b   c") == _normalised_hash("a b c")
+
+    def test_ignores_leading_trailing_whitespace(self):
+        assert _normalised_hash("  hello  ") == _normalised_hash("hello")
+
+    def test_ignores_newlines_vs_spaces(self):
+        assert _normalised_hash("hello\nworld") == _normalised_hash("hello world")
+
+    def test_differs_for_different_content(self):
+        assert _normalised_hash("alpha") != _normalised_hash("beta")
+
+
+# ── _simhash ──────────────────────────────────────────────────────────────────
+
+
+class TestSimhash:
+    def test_identical_text_distance_zero(self):
+        text = "The quick brown fox jumps over the lazy dog"
+        h1 = _simhash(text)
+        h2 = _simhash(text)
+        assert _hamming_distance(h1, h2) == 0
+
+    def test_similar_text_smaller_than_different(self):
+        t1 = "The quick brown fox jumps over the lazy dog"
+        t2 = "The quick brown fox leaps over the lazy dog"
+        t3 = "Lorem ipsum dolor sit amet consectetur adipiscing elit"
+        d_similar = _hamming_distance(_simhash(t1), _simhash(t2))
+        d_different = _hamming_distance(_simhash(t1), _simhash(t3))
+        assert d_similar < d_different, f"Similar ({d_similar}) should be < different ({d_different})"
+
+    def test_different_text_large_distance(self):
+        t1 = "The quick brown fox jumps over the lazy dog"
+        t2 = "Lorem ipsum dolor sit amet consectetur adipiscing elit"
+        d = _hamming_distance(_simhash(t1), _simhash(t2))
+        assert d > 5, f"Expected large distance, got {d}"
+
+    def test_returns_int(self):
+        assert isinstance(_simhash("test text here"), int)
+
+    def test_short_text_does_not_crash(self):
+        # Short text triggers character-level fallback
+        h = _simhash("hi")
+        assert isinstance(h, int)
+
+
+# ── _hamming_distance ─────────────────────────────────────────────────────────
+
+
+class TestHammingDistance:
+    def test_identical_values(self):
+        assert _hamming_distance(0b1010, 0b1010) == 0
+
+    def test_one_bit_difference(self):
+        assert _hamming_distance(0b1010, 0b1011) == 1
+
+    def test_all_bits_different(self):
+        assert _hamming_distance(0b0000, 0b1111) == 4
+
+    def test_known_pattern(self):
+        # 0xFF ^ 0x00 = 0xFF → 8 bits set
+        assert _hamming_distance(0xFF, 0x00) == 8
+
+    def test_symmetric(self):
+        assert _hamming_distance(42, 99) == _hamming_distance(99, 42)
+
+    def test_zero_zero(self):
+        assert _hamming_distance(0, 0) == 0