OgbujiPT 0.10.0 Phase 1: Foundation & Rearchitecture

[uogbuji]

First major step toward transforming OgbujiPT into a general-purpose LLMOps knowledge bank system, as outlined in discussion #92. This phase focuses on establishing a solid foundation through code reorganization and introducing core retrieval capabilities.

For a quick intro to the new changes, a good start is the demo/pg-hybrid dir.

Major Changes

Code Reorg

• Module restructuring: Moved modules into logical packages:
  • llm_wrapper.py → llm/wrapper.py
  • embedding/ → store/postgres/ (pgvector modules)
  • embedding/qdrant.py → store/qdrant/collection.py
  • text_helper.py → text/splitter.py
  • html_helper.py → text/html.py
• New package structure:
  • pylib/retrieval/ - Search strategies (dense, sparse, hybrid)
  • pylib/memory/ - Knowledge base interfaces and metadata
  • pylib/store/ - Storage backends (postgres, qdrant)
  • pylib/llm/ - LLM wrapper functionality
  • pylib/text/ - Text processing utilities

New Retrieval Capabilities

• Sparse retrieval (retrieval/sparse.py): BM25 implementation for keyword-based search
• Dense retrieval (retrieval/dense.py): Wrapper for embedding-based semantic search
• Hybrid search (retrieval/hybrid.py): Reciprocal Rank Fusion (RRF) combining multiple strategies

Memory/Knowledge Base Foundation

• KBBackend protocol (memory/base.py): Protocol-based interface for knowledge base backends (vector stores, graph DBs, etc.)
• SearchStrategy protocol: Interface for pluggable search strategies
• SearchResult dataclass: Unified result format across all backends
• Metadata support (memory/metadata.py): Foundation for enriched item metadata

PostgreSQL Enhancements

• Sparse vector support (store/postgres/pgvector_sparse.py): BM25-compatible sparse vector storage using pgvector
• Hybrid search demos (demo/pg-hybrid/): Complete examples showing dense + sparse retrieval

Removed Deprecated Code

• pylib/prompting/ - Old prompting utilities (replaced by direct LLM wrapper usage)
• pylib/word_loom.py - Deprecated prompt loading system
• pylib/memoization/ - Moved to store/postgres/pgmemo.py
• Various demo files that are no longer relevant

Updated Imports

All imports across the codebase have been updated to reflect the new structure. This includes:

• Demo scripts (chat_web_selects.py, chat_doc_folder.py, etc.)
• Test files
• Internal module imports

Testing

• Updated test paths to match new module structure
• Existing tests continue to pass with updated imports
• New retrieval functionality demonstrated in demo/pg-hybrid/

Documentation & Examples

• demo/pg-hybrid/README.md: Comprehensive guide to hybrid search
• demo/pg-hybrid/hybrid_search.ipynb: Interactive Jupyter notebook tutorial
• demo/pg-hybrid/chat_with_hybrid_kb.py: Full conversational RAG example with hybrid search
• demo/pg-hybrid/hybrid_search_demo.py: Standalone hybrid search demonstration

Migration Notes

For users upgrading:

1. Import paths have changed:

   • ogbujipt.llm_wrapper → ogbujipt.llm.wrapper
   • ogbujipt.embedding.* → ogbujipt.store.postgres.* or ogbujipt.store.qdrant.*
   • ogbujipt.text_helper → ogbujipt.text.splitter
   • ogbujipt.html_helper → ogbujipt.text.html

2. New capabilities available:

   • Use ogbujipt.retrieval.hybrid.HybridSearch for combining dense + sparse search
   • Use ogbujipt.retrieval.sparse.BM25Search for keyword-based retrieval
   • Implement KBBackend protocol for custom storage backends

Next Steps (Future PRs)

This foundation enables future work on:

• GraphRAG support using Onya
• Query classification/routing
• Multi-backend aggregation
• Observability and query logging
• Maintenance and pruning strategies
• MCP provider/server

Checklist

• Code reorganization complete
• Retrieval abstraction layer implemented
• Hybrid search working with PostgreSQL
• All imports updated
• Tests updated and passing
• Documentation and examples added
• Deprecated code removed
• CI/CD workflows updated

[uogbuji]

Ended up on a bit of an extended detour today. CI tests were failing because they required a running PostgreSQL server with pgvector extension:

ERROR test/store/test_pgvector_data.py - OSError: Connect call failed ('127.0.0.1', 5432)

14 tests were blocked by this dependency, requiring complex CI setup (DB services, connection management, etc.). I could dip into the well of more and more mocking, but this can become brittle and unwieldy, especially trying to mock database operations directly.

I always like the reasoning from the Hynek article "'Don’t Mock What You Don’t Own' in 5 Minutes". The better approach is "own your I/O boundaries"—create your own abstraction and provide alternative implementations rather than always mocking third-party libraries.

Solution

I'd always wanted to have production-ready in-memory vector stores as a lightweight option for end users in prototyping, demos, and embedded. Might as well get to that, with the dual use of embodying fast, dependency-free tests of the OgbujiPT store components.

Changes

1. In-Memory Vector Store Implementation (pylib/store/memory.py)

• InMemoryDataDB - Drop-in replacement for DataDB (document/snippet storage)
• InMemoryMessageDB - Drop-in replacement for MessageDB (chat/message storage)

Features:

• Full API compatibility with PostgreSQL versions
• Numpy-based cosine similarity calculations
• Complete metadata filtering support
• Windowing support for message history
• UUID string-to-object conversion
• Abstracted lifecycle methods (setup()/cleanup() with compatibility aliases)

2. Test Infrastructure Updates (test/store/conftest.py)

• Default fixtures now use in-memory stores (no external dependencies)
• PG_DB* fixtures added for optional PostgreSQL integration tests
• Automatic selection based on test file type (data vs message)

3. Pytest Configuration via pyproject.toml

Tip of these changes: bd97864

In-memory DB Usage Example

from ogbujipt.store.memory import InMemoryDataDB

# Use in-memory store (no PostgreSQL required)
db = InMemoryDataDB(embedding_model=model, collection_name='my_docs')
await db.setup()

await db.insert('Hello world', metadata={'source': 'greeting'})
async for result in db.search('greeting', limit=5):
    print(result.content, result.score)

await db.cleanup()

Testing

All existing PG tests pass with in-memory implementation. Note: there's still a qdrant test I need to nurse back to health. To run PostgreSQL integration tests:

# Default: fast in-memory tests
pytest test/store/ -v

# With PostgreSQL (requires running instance)
pytest test/store/ -v -m integration

Follow-up Work

• Add demo files paralleling demo/pg-hybrid using in-memory stores
• Update test/store/README.md with usage examples
• Add docstring examples for in-memory stores

n.b. 1: Finally added a CONTRIBUTING.md

n.b. 2: Oh yes; I got help from Claude Code in this, but as always under a ton of supervision and constraint.