our-embeddings 0.1.0__tar.gz

our_embeddings-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    uses: ourochronos/our-infra/.github/workflows/lint.yml@main
+    with:
+      extra-install: "git+https://github.com/ourochronos/our-db.git"
+  test:
+    needs: lint
+    uses: ourochronos/our-infra/.github/workflows/test.yml@main
+    with:
+      extra-install: "git+https://github.com/ourochronos/our-db.git"

our_embeddings-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,13 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    uses: ourochronos/our-infra/.github/workflows/release.yml@main
+    secrets: inherit

our_embeddings-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

our_embeddings-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--config-file=pyproject.toml]
+        stages: [commit]
+        language: system
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.8
+    hooks:
+      - id: bandit
+        args: ['-q', '--severity-level', 'medium']
+        exclude: tests/

our_embeddings-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure

our_embeddings-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Jacobs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

our_embeddings-0.1.0/Makefile

@@ -0,0 +1,38 @@
+.PHONY: help install dev lint format test test-unit test-int test-cov clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install package
+	pip install -e .
+
+dev: ## Install package with dev dependencies
+	pip install -e ".[dev]"
+	pre-commit install
+
+lint: ## Run linters (ruff + mypy)
+	ruff check src/ tests/
+	ruff format --check src/ tests/
+	mypy src/
+
+format: ## Auto-format code
+	ruff check --fix src/ tests/
+	ruff format src/ tests/
+
+test: test-unit ## Run tests (unit only by default)
+
+test-unit: ## Run unit tests
+	pytest tests/ -m "not integration and not slow" -v
+
+test-int: ## Run integration tests
+	pytest tests/ -m integration -v --timeout=60
+
+test-all: ## Run all tests
+	pytest tests/ -v --timeout=120
+
+test-cov: ## Run tests with coverage report
+	pytest tests/ -m "not integration and not slow" --cov --cov-report=term-missing --cov-report=html
+
+clean: ## Remove build artifacts and caches
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

our_embeddings-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: our-embeddings
+Version: 0.1.0
+Summary: Vector embedding generation and similarity search
+Project-URL: Homepage, https://github.com/ourochronos/our-embeddings
+Project-URL: Repository, https://github.com/ourochronos/our-embeddings
+Author: Chris Jacobs
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: openai>=1.0
+Requires-Dist: our-db>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: numpy>=1.24; extra == 'local'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'local'
+Description-Content-Type: text/markdown
+
+# our-embeddings
+
+Vector embedding generation and similarity search for the ourochronos ecosystem.
+
+## Overview
+
+our-embeddings provides a unified interface for generating and searching vector embeddings. It supports both local (sentence-transformers) and OpenAI providers, with a federation standard for cross-node embedding compatibility.
+
+Default model: **BAAI/bge-small-en-v1.5** (384 dimensions, L2-normalized).
+
+## Install
+
+```bash
+pip install our-embeddings
+```
+
+For local embeddings (default, no API key needed):
+```bash
+pip install our-embeddings[local]  # includes sentence-transformers
+```
+
+## Usage
+
+### Generate Embeddings
+
+```python
+from our_embeddings.service import generate_embedding, vector_to_pgvector
+
+# Generate a 384-dim embedding vector
+vector = generate_embedding("PostgreSQL is excellent for JSONB queries")
+
+# Convert to pgvector format for storage
+pg_str = vector_to_pgvector(vector)
+# → "[0.0231,0.0891,...]"
+```
+
+### Search Similar Content
+
+```python
+from our_embeddings import search_similar
+
+results = search_similar(
+    query="database performance",
+    content_type="belief",
+    limit=10,
+    min_similarity=0.5,
+)
+# Returns list of dicts with id, content, similarity score
+```
+
+### Embed and Store
+
+```python
+from our_embeddings import embed_content
+
+result = embed_content(
+    content_type="belief",
+    content_id="uuid-here",
+    text="Valence uses dimensional confidence",
+)
+```
+
+### Batch Operations
+
+```python
+from our_embeddings.local import generate_embeddings_batch
+
+vectors = generate_embeddings_batch(
+    ["text one", "text two", "text three"],
+    batch_size=32,
+)
+```
+
+### Backfill Missing Embeddings
+
+```python
+from our_embeddings import backfill_embeddings
+
+count = backfill_embeddings(content_type="belief", batch_size=100)
+```
+
+## Configuration
+
+### EmbeddingConfig
+
+```python
+from our_embeddings.config import EmbeddingConfig
+
+config = EmbeddingConfig.from_env()
+# Fields:
+#   embedding_provider: str = "local"
+#   embedding_model_path: str = "BAAI/bge-small-en-v1.5"
+#   embedding_device: str = "cpu"
+#   openai_api_key: str = ""
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VALENCE_EMBEDDING_PROVIDER` | `local` | `"local"` or `"openai"` |
+| `VALENCE_EMBEDDING_MODEL_PATH` | `BAAI/bge-small-en-v1.5` | Model name or path |
+| `VALENCE_EMBEDDING_DEVICE` | `cpu` | `"cpu"` or `"cuda"` |
+| `OPENAI_API_KEY` | — | Required if provider is `openai` |
+
+## Providers
+
+### Local (default)
+
+Uses sentence-transformers with BAAI/bge-small-en-v1.5:
+- 384 dimensions, L2-normalized
+- No API key required
+- Model loaded lazily and cached as singleton
+- Thread-safe initialization
+
+### OpenAI
+
+Uses OpenAI text-embedding-3-small:
+- 1536 dimensions
+- Requires `OPENAI_API_KEY`
+- Text truncated to 8000 chars
+
+## Embedding Type Registry
+
+Register and manage multiple embedding types:
+
+```python
+from our_embeddings import register_embedding_type, list_embedding_types
+
+register_embedding_type(
+    type_id="local_bge_small",
+    provider="local",
+    model="BAAI/bge-small-en-v1.5",
+    dimensions=384,
+    is_default=True,
+)
+
+types = list_embedding_types(status="active")
+```
+
+## Federation Standard
+
+Cross-node embedding compatibility for federated knowledge sharing:
+
+```python
+from our_embeddings import get_federation_standard, validate_federation_embedding
+
+standard = get_federation_standard()
+# → {"model": "BAAI/bge-small-en-v1.5", "dimensions": 384,
+#    "type": "bge_small_en_v15", "normalization": "L2", "version": "1.0"}
+
+valid, error = validate_federation_embedding([0.1, 0.2, ...])
+```
+
+Federation functions for belief exchange:
+- `prepare_belief_for_federation(belief_id)` — Package belief with embedding
+- `validate_incoming_belief_embedding(data)` — Validate received embeddings
+- `regenerate_embedding_if_needed(data)` — Re-embed if format differs
+
+## State Ownership
+
+Owns the `embedding_types` and `embedding_coverage` tables in the valence schema. Reads/writes the `embedding` column on `beliefs`, `vkb_exchanges`, and `vkb_patterns` tables.
+
+## Development
+
+```bash
+make dev       # Install with dev dependencies
+make lint      # Run linters
+make test      # Run tests
+make test-cov  # Tests with coverage
+make format    # Auto-format
+```
+
+## Part of Valence
+
+This brick is part of the [Valence](https://github.com/ourochronos/valence) knowledge substrate. See [our-infra](https://github.com/ourochronos/our-infra) for ourochronos conventions.
+
+## License
+
+MIT

our_embeddings-0.1.0/README.md

@@ -0,0 +1,180 @@
+# our-embeddings
+
+Vector embedding generation and similarity search for the ourochronos ecosystem.
+
+## Overview
+
+our-embeddings provides a unified interface for generating and searching vector embeddings. It supports both local (sentence-transformers) and OpenAI providers, with a federation standard for cross-node embedding compatibility.
+
+Default model: **BAAI/bge-small-en-v1.5** (384 dimensions, L2-normalized).
+
+## Install
+
+```bash
+pip install our-embeddings
+```
+
+For local embeddings (default, no API key needed):
+```bash
+pip install our-embeddings[local]  # includes sentence-transformers
+```
+
+## Usage
+
+### Generate Embeddings
+
+```python
+from our_embeddings.service import generate_embedding, vector_to_pgvector
+
+# Generate a 384-dim embedding vector
+vector = generate_embedding("PostgreSQL is excellent for JSONB queries")
+
+# Convert to pgvector format for storage
+pg_str = vector_to_pgvector(vector)
+# → "[0.0231,0.0891,...]"
+```
+
+### Search Similar Content
+
+```python
+from our_embeddings import search_similar
+
+results = search_similar(
+    query="database performance",
+    content_type="belief",
+    limit=10,
+    min_similarity=0.5,
+)
+# Returns list of dicts with id, content, similarity score
+```
+
+### Embed and Store
+
+```python
+from our_embeddings import embed_content
+
+result = embed_content(
+    content_type="belief",
+    content_id="uuid-here",
+    text="Valence uses dimensional confidence",
+)
+```
+
+### Batch Operations
+
+```python
+from our_embeddings.local import generate_embeddings_batch
+
+vectors = generate_embeddings_batch(
+    ["text one", "text two", "text three"],
+    batch_size=32,
+)
+```
+
+### Backfill Missing Embeddings
+
+```python
+from our_embeddings import backfill_embeddings
+
+count = backfill_embeddings(content_type="belief", batch_size=100)
+```
+
+## Configuration
+
+### EmbeddingConfig
+
+```python
+from our_embeddings.config import EmbeddingConfig
+
+config = EmbeddingConfig.from_env()
+# Fields:
+#   embedding_provider: str = "local"
+#   embedding_model_path: str = "BAAI/bge-small-en-v1.5"
+#   embedding_device: str = "cpu"
+#   openai_api_key: str = ""
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VALENCE_EMBEDDING_PROVIDER` | `local` | `"local"` or `"openai"` |
+| `VALENCE_EMBEDDING_MODEL_PATH` | `BAAI/bge-small-en-v1.5` | Model name or path |
+| `VALENCE_EMBEDDING_DEVICE` | `cpu` | `"cpu"` or `"cuda"` |
+| `OPENAI_API_KEY` | — | Required if provider is `openai` |
+
+## Providers
+
+### Local (default)
+
+Uses sentence-transformers with BAAI/bge-small-en-v1.5:
+- 384 dimensions, L2-normalized
+- No API key required
+- Model loaded lazily and cached as singleton
+- Thread-safe initialization
+
+### OpenAI
+
+Uses OpenAI text-embedding-3-small:
+- 1536 dimensions
+- Requires `OPENAI_API_KEY`
+- Text truncated to 8000 chars
+
+## Embedding Type Registry
+
+Register and manage multiple embedding types:
+
+```python
+from our_embeddings import register_embedding_type, list_embedding_types
+
+register_embedding_type(
+    type_id="local_bge_small",
+    provider="local",
+    model="BAAI/bge-small-en-v1.5",
+    dimensions=384,
+    is_default=True,
+)
+
+types = list_embedding_types(status="active")
+```
+
+## Federation Standard
+
+Cross-node embedding compatibility for federated knowledge sharing:
+
+```python
+from our_embeddings import get_federation_standard, validate_federation_embedding
+
+standard = get_federation_standard()
+# → {"model": "BAAI/bge-small-en-v1.5", "dimensions": 384,
+#    "type": "bge_small_en_v15", "normalization": "L2", "version": "1.0"}
+
+valid, error = validate_federation_embedding([0.1, 0.2, ...])
+```
+
+Federation functions for belief exchange:
+- `prepare_belief_for_federation(belief_id)` — Package belief with embedding
+- `validate_incoming_belief_embedding(data)` — Validate received embeddings
+- `regenerate_embedding_if_needed(data)` — Re-embed if format differs
+
+## State Ownership
+
+Owns the `embedding_types` and `embedding_coverage` tables in the valence schema. Reads/writes the `embedding` column on `beliefs`, `vkb_exchanges`, and `vkb_patterns` tables.
+
+## Development
+
+```bash
+make dev       # Install with dev dependencies
+make lint      # Run linters
+make test      # Run tests
+make test-cov  # Tests with coverage
+make format    # Auto-format
+```
+
+## Part of Valence
+
+This brick is part of the [Valence](https://github.com/ourochronos/valence) knowledge substrate. See [our-infra](https://github.com/ourochronos/our-infra) for ourochronos conventions.
+
+## License
+
+MIT

our_embeddings-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "our-embeddings"
+version = "0.1.0"
+description = "Vector embedding generation and similarity search"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Chris Jacobs" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "our-db>=0.1.0",
+    "openai>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ourochronos/our-embeddings"
+Repository = "https://github.com/ourochronos/our-embeddings"
+
+[project.optional-dependencies]
+local = [
+    "sentence-transformers>=2.2.0",
+    "numpy>=1.24",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "pytest-mock>=3.12",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pre-commit>=3.7",
+    "numpy>=1.24",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/our_embeddings"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["our_embeddings"]
+
+[tool.mypy]
+python_version = "3.11"
+disallow_untyped_defs = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = [
+    "our_db",
+    "our_db.*",
+    "openai",
+    "openai.*",
+    "sentence_transformers",
+    "sentence_transformers.*",
+    "numpy",
+    "numpy.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: Unit tests (no external dependencies)",
+    "integration: Integration tests (require external services)",
+    "slow: Slow tests (>5s)",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/our_embeddings"]
+
+[tool.coverage.report]
+show_missing = true