fix(py): harden cognitive nexus bindings

Update the Python binding package for the Cognitive Nexus 0.8 release.

- bump anda_cognitive_nexus_py to 0.3.0 and depend on 0.8 Rust crates
- add an idempotent async close API for flushing file-backed stores
- convert Python KIP parameters directly into JSON-compatible values
- return ValueError for unsupported parameters instead of panicking
- add PyO3 extension-module link args and a release-py wheel profile
- point maturin at the binding crate manifest and refresh README examples
- cover invalid parameters, nested parameters, and close idempotency
- document the Python binding changes in the 0.8.0 changelog

Co-Authored-By: Anda Bot <noreply@anda.bot>

Author: zensh

CHANGELOG.md

@@ -10,11 +10,14 @@ All notable changes to this workspace are documented in this file.
 - **KIP recall and portability commands** — Extended `SEARCH` with retrieval modes (`keyword`, `semantic`, `hybrid`) and score thresholds, and added `EXPORT` for serializing matched knowledge into idempotent UPSERT capsules.
 - **Commitment capsule** — Added the `Commitment.kip` capsule and updated built-in capsule metadata so agents can model durable commitments alongside events and people.
 - **Cognitive Nexus KIP execution coverage** — Implemented KML/KQL/META support for the expanded KIP surface, including update execution, merge handling, search scoring, export generation, and version-conflict reporting.
-- **Regression coverage for KIP and Cognitive Nexus behavior** — Added parser and executor tests for optimistic concurrency, update expressions, merge semantics, search modes, export capsules, and the split database implementation.
+- **Python binding close API** — Added an idempotent async `PyAndaDB.close()` method so Python clients can explicitly flush and close file-backed Cognitive Nexus stores.
+- **Regression coverage for KIP, Cognitive Nexus, and Python binding behavior** — Added parser, executor, and Python tests for optimistic concurrency, update expressions, merge semantics, search modes, export capsules, split database behavior, parameter conversion failures, nested parameters, and close idempotency.
 
 ### Changed
 
 - **Workspace crates moved to the 0.8 line** — Bumped `anda_db`, `anda_kip`, and `anda_cognitive_nexus` to `0.8.0`, and updated dependent workspace crates to require the matching `0.8` APIs.
+- **Python binding moved to the 0.3 line** — Bumped `anda_cognitive_nexus_py` to `0.3.0`, updated it to depend on the `0.8` Rust crates, and switched the Python package metadata to derive its version from the binding crate manifest.
+- **Python wheel build profile clarified** — Added a `release-py` profile for PyO3 extension wheels and pointed maturin at the binding crate manifest.
 - **Cognitive Nexus database implementation split by responsibility** — Replaced the monolithic `db.rs` with focused modules for KML execution, KQL execution, proposition matching, META commands, shared database setup, and tests.
 - **KIP specification and tool schemas refreshed** — Updated the specification, syntax guide, self/system instructions, and function definition JSON files to describe the RC KIP semantics and the new read/write command set.
 - **System metadata semantics clarified** — Documented reserved engine-maintained `_` metadata fields, versioning behavior, and protected-scope constraints for write operations.
@@ -23,3 +26,5 @@ All notable changes to this workspace are documented in this file.
 
 - **Safer endpoint matching syntax** — Tightened embedded endpoint clause handling so nested concept/proposition endpoints remain unnamed, with explicit guidance for binding endpoints through separate clauses.
 - **More robust query and mutation behavior** — Hardened Cognitive Nexus helper/type paths around KIP execution, protected scopes, cache invalidation, and proposition matching while preserving concurrent read and exclusive write semantics.
+- **Safer Python parameter handling** — Replaced panic-prone JSON string round-tripping with direct JSON-compatible Python value conversion and clear `ValueError` failures for unsupported values, non-finite floats, non-string keys, and excessive nesting.
+- **Python extension import/build robustness** — Made logger initialization non-fatal when a host process already installed a logger, added PyO3 macOS extension link arguments, and documented the correct module import path in the Python README.

Cargo.toml

@@ -16,8 +16,9 @@ members = [
   "rs/anda_db_shard_proxy",
   # "py/anda_cognitive_nexus_py",
 ]
-# Python binding package (anda_cognitive_nexus_py) is excluded from workspace testing
-# because it requires Python library linking. Test it separately with:
+# The Python binding (anda_cognitive_nexus_py) is excluded from default workspace
+# builds because it links against a Python interpreter. To build or test it,
+# temporarily uncomment the member above, then:
 #   cargo test -p anda_cognitive_nexus_py --lib
 
 [workspace.package]
@@ -105,6 +106,7 @@ regex = { version = "1.11", default-features = false }
 rustc-hash = { version = "2", default-features = false, features = ["std"] }
 pyo3 = { version = "0.20", default-features = false }
 pyo3-asyncio = { version = "0.20", default-features = false }
+pyo3-build-config = { version = "0.20" }
 serde-pyobject = { version = "0.2", default-features = false }
 mimalloc = { version = "0.1", features = ["v3"] }
 
@@ -118,3 +120,10 @@ strip = true
 opt-level = 'z'
 codegen-units = 1
 panic = "abort"
+
+# Python extension wheels must unwind on panic so PyO3 can turn panics into
+# Python exceptions instead of aborting the host interpreter.
+# Build with: maturin build --profile release-py
+[profile.release-py]
+inherits = "release"
+panic = "unwind"

py/anda_cognitive_nexus_py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "anda_cognitive_nexus_py"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 
 [lib]
@@ -10,23 +10,21 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 # Python Bindings
 pyo3 = { workspace = true, features = ["extension-module", "serde"] }
-pyo3-asyncio = { workspace = true, features = [
-  "attributes",
-  "async-std-runtime",
-  "tokio-runtime",
-] }
-tokio = { workspace = true }
+pyo3-asyncio = { workspace = true, features = ["tokio-runtime"] }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
 serde-pyobject = { workspace = true }
 
 # Anda
-anda_cognitive_nexus = { version = "0.7", path = "../../rs/anda_cognitive_nexus" }
-anda_kip = { version = "0.7", path = "../../rs/anda_kip" }
-anda_db = { version = "0.7", path = "../../rs/anda_db", features = ["full"] }
+anda_cognitive_nexus = { version = "0.8", path = "../../rs/anda_cognitive_nexus" }
+anda_kip = { version = "0.8", path = "../../rs/anda_kip" }
+anda_db = { version = "0.8", path = "../../rs/anda_db", features = ["full"] }
 anda_object_store = { version = "0.3", path = "../../rs/anda_object_store" }
 
 # Other Crates
-serde_json = { workspace = true }
 serde = { workspace = true }
 object_store = { workspace = true }
 log = { workspace = true }
 structured-logger = { workspace = true }
+
+[build-dependencies]
+pyo3-build-config = { workspace = true }

py/anda_cognitive_nexus_py/README.md

@@ -56,7 +56,14 @@ uv pip install -r tests_py/requirements.txt
 maturin develop
 ```
 
-After this step, the `anda` module is available to be imported in any Python script run from this activated environment.
+After this step, the `anda_cognitive_nexus_py` module is available to be imported in any Python script run from this activated environment.
+
+To build a release wheel, use the `release-py` profile so panics unwind into
+Python exceptions instead of aborting the interpreter:
+
+```bash
+maturin build --profile release-py
+```
 
 ## Running Tests
 
@@ -85,7 +92,7 @@ To quickly verify your setup, you can run the following Python script:
 
 ```python
 # main.py
-import anda
+import anda_cognitive_nexus_py as anda
 
 # This is the "hello world" function currently implemented
 result = anda.sum_as_string(10, 20)
@@ -111,7 +118,7 @@ python main.py
 The API now exposes configuration and enums as Python classes, not dicts or strings. Construct configs using `AndaDbConfig` and `StoreLocationType` directly:
 
 ```python
-import anda
+import anda_cognitive_nexus_py as anda
 
 # Construct the config using Python classes (not dicts)
 config = anda.AndaDbConfig(
@@ -126,9 +133,16 @@ config = anda.AndaDbConfig(
 import asyncio
 async def main():
 	db = await anda.PyAndaDB.create(config)
-	# Execute a KIP command (async)
-	result = await db.execute_kip("KIP_COMMAND_STRING")
-	print(result)  # result is a Python dict, not a JSON string
+	try:
+		# Execute a KIP command (async), optionally with :name parameters
+		result = await db.execute_kip(
+			"FIND(?t.name) WHERE { ?t {type: :t} } LIMIT 10",
+			parameters={"t": "$ConceptType"},
+		)
+		print(result)  # result is a Python dict, not a JSON string
+	finally:
+		# Flush pending data to storage; required for file-backed stores.
+		await db.close()
 
 asyncio.run(main())
 ```

py/anda_cognitive_nexus_py/build.rs

@@ -0,0 +1,5 @@
+fn main() {
+    // With pyo3's `extension-module` feature, libpython is not linked; on macOS the
+    // cdylib needs `-undefined dynamic_lookup` so `cargo build/run` works outside maturin.
+    pyo3_build_config::add_extension_module_link_args();
+}