Skip to content

Migrating from pss

For the full import table, numerical-fidelity envelope, and known drift caveats, see the project-root MIGRATION.md.

Migrating from semvec 0.1.x to 0.2.x

The 0.2.0a1 line introduces one substantive API shift: the calculate_* primitives are no longer free functions on _core but methods on SemvecState. The free functions remain importable for byte-identical legacy behaviour, with a DeprecationWarning on every call.

Pre-0.2.0 0.2.0+
from semvec import _core; _core.calculate_fsm(history, ...) state.calculate_fsm(history, ...)
_core.calculate_metrics(...) state.calculate_metrics(...)
_core.calculate_advanced_metrics(...) state.calculate_advanced_metrics(...)

The state-bound methods salt their numeric inputs with a hidden value derived from the active license subject (SEMVEC_LICENSE_KEY) and the state's dimension. Output trajectories are deterministic given a (subject, dimension, input) tuple but differ from the unsalted reference — that is the patent-protection point. If you need byte-identical pre-0.2.0 numerics for a parity test against the original pss reference, keep using the deprecated free functions; for production code, migrate to the methods.

The legacy PSS_State_V4 / PSSConfig / PSSChatProxy aliases are now scheduled for removal in 1.0 (was 0.2.0); they continue to work in 0.2.x with a DeprecationWarning.

The short version

Most code needs only an import rewrite — from pss.X import Y becomes from semvec.X import Y. Two subsystems were renamed into product-branded namespaces:

pss namespace semvec namespace
pss.network semvec.cortex
pss.compaction semvec.coding

All class names inside these namespaces are unchanged except CompactionEngine → CodingEngine.

Behavioural differences

  1. Explicit embedder. SemvecAgent, CodingEngine, SemvecChatProxy, and the LongMemEval runners no longer silently fall back to hash-based pseudo-embeddings. Pass embedder= / embedding_service=, or install sentence-transformers. Missing embedder raises RuntimeError with a copy-paste SentenceTransformer wrapper in the message.

  2. Licensing. pss had no license check. semvec enforces a signed JWT for Pro/Enterprise APIs and rate-limits Community usage. Set SEMVEC_LICENSE_KEY before import. See Licensing.

  3. ConsensusEngine.create_proposal returns a ConsensusProposal object (not a str) — matches pss semantics. Vote changes made through the engine are reflected in the returned object via an internal Arc<Mutex<>>.

  4. Bit-exact parity API. SemvecState.set_retrieval_projection_weights(matrix) lets you inject pss.core.RetrievalProjection.W_down for bit-identical first-5-turn behaviour. The mirror getters get_retrieval_projection_weights() and get_retrieval_projection_w_up() snapshot the current matrices.

What is NOT ported

  • pss.integrations.{deepagents, langchain, postgresql, neo4j} — framework adapters, stay user-side.
  • pss.embedding.EmbeddingService — SentenceTransformer-backed implementation lives in user-space; semvec._core.EmbeddingService is an isinstance-compatible stub only.
  • pss.benchmarks.longmemeval.Mem0Runner — requires external mem0ai, not shipped.
  • CLI demo scripts (demo.py, live_demo.py, interactive_chat.py) — user-onboarding only.

See MIGRATION.md §What was intentionally dropped for the full list and rationale.