Skip to main content

Proof of concept, not a product. This library belongs to the earlier Python research prototype (Socrates) and is not maintained as a product. The current products are listed at nireus79.github.io. Contact: Hermes_creative@proton.me.

Socratic Knowledge

Tests Code Quality PyPI License: MIT

Why Socratic Knowledge?

Shared knowledge bases need multi-tenancy and access control. Socratic Knowledge provides:

  • Multi-Tenancy - Separate knowledge spaces for multiple organizations with tenant-level access control
  • Access Control - Role-based permissions (RBAC) with fine-grained control: Viewer, Editor, Admin, Owner
  • Full Versioning - Complete history tracking with rollback capabilities for all changes
  • Semantic Search - Semantic search with embeddings
  • Audit Logging - Audit trail of changes and access

Knowledge management system with multi-tenancy, access control, versioning, and RAG integration.

Features

  • 📚 Knowledge Organization - Hierarchical knowledge base with collections and documents
  • 🔐 Multi-Tenancy - Isolated knowledge spaces for multiple organizations
  • 👥 Access Control - Role-based permissions (RBAC) with fine-grained control
  • 📝 Versioning - Full history tracking with rollback capabilities
  • 🔍 Semantic Search - RAG-powered semantic search with embeddings
  • 🤝 Collaboration - Multi-user editing with conflict detection
  • 📋 Audit Logging - Audit trail of changes and access
  • 🔌 Framework Integration - Works with Openclaw and LangChain

Quick Start

Installation

# Basic installation
pip install socratic-knowledge

# With RAG integration
pip install socratic-knowledge[rag]

# With LangChain integration
pip install socratic-knowledge[langchain]

# Everything
pip install socratic-knowledge[all]

Simple Example

from socratic_knowledge import KnowledgeManager

# Create knowledge manager
km = KnowledgeManager(storage="sqlite", db_path="knowledge.db")

# Create tenant (organization)
tenant = km.create_tenant(name="Acme Corp", domain="acme.com")

# Create collection (folder)
docs = km.create_collection(
    tenant_id=tenant.tenant_id,
    name="Documentation",
    created_by="user123"
)

# Add knowledge item
item = km.create_item(
    tenant_id=tenant.tenant_id,
    collection_id=docs.collection_id,
    title="API Guide",
    content="How to use our API...",
    created_by="user123",
    tags=["api", "guide"]
)

# Search
results = km.search(tenant_id=tenant.tenant_id, query="API")

# Get item
retrieved = km.get_item(item.item_id, tenant_id=tenant.tenant_id)

Core Concepts

KnowledgeItem

The main entity representing any knowledge artifact (document, note, etc.)

@dataclass
class KnowledgeItem:
    item_id: str                    # UUID
    tenant_id: str                  # For multi-tenancy
    collection_id: Optional[str]    # Parent collection
    title: str
    content: str
    content_type: str               # "text", "markdown", "json"
    version: int
    created_at: datetime
    updated_at: datetime
    created_by: str
    updated_by: str
    owner_id: str
    permissions: Dict[str, List[str]]  # {role: [user_ids]}
    tags: List[str]
    metadata: Dict[str, Any]

Collection

Hierarchical container for organizing knowledge items (like folders)

@dataclass
class Collection:
    collection_id: str
    tenant_id: str
    parent_id: Optional[str]        # For hierarchy
    name: str
    owner_id: str
    permissions: Dict[str, List[str]]
    inherit_permissions: bool       # Inherit ACL from parent

Tenant

Organization/account for multi-tenancy support

@dataclass
class Tenant:
    tenant_id: str
    name: str
    domain: Optional[str]           # e.g., "acme.com"
    max_storage_mb: int
    is_active: bool

Access Control

Role-based permissions (RBAC):

  • VIEWER - Read only
  • EDITOR - Read + Write
  • ADMIN - Full access
  • OWNER - All permissions

API Reference

KnowledgeManager

Main interface for knowledge management operations.

class KnowledgeManager:
    # Tenant operations
    def create_tenant(self, name: str, **kwargs) -> Tenant
    def get_tenant(self, tenant_id: str) -> Optional[Tenant]

    # Collection operations
    def create_collection(self, tenant_id: str, name: str, created_by: str,
                         parent_id: Optional[str] = None) -> Collection
    def get_collection(self, collection_id: str) -> Optional[Collection]
    def list_collections(self, tenant_id: str, parent_id: Optional[str] = None) -> List[Collection]

    # Knowledge item operations
    def create_item(self, tenant_id: str, title: str, content: str,
                   created_by: str, collection_id: Optional[str] = None,
                   **kwargs) -> KnowledgeItem
    def get_item(self, item_id: str, tenant_id: str) -> Optional[KnowledgeItem]
    def update_item(self, item: KnowledgeItem, change_message: str = "") -> KnowledgeItem
    def delete_item(self, item_id: str, tenant_id: str, soft: bool = True) -> bool
    def list_items(self, tenant_id: str, collection_id: Optional[str] = None,
                  limit: int = 100, offset: int = 0) -> List[KnowledgeItem]

    # Search operations
    def search(self, tenant_id: str, query: str, limit: int = 10) -> List[KnowledgeItem]
    def semantic_search(self, tenant_id: str, query: str, top_k: int = 5,
                       collection_id: Optional[str] = None) -> List[KnowledgeItem]

    # Access control
    def grant_permission(self, item_id: str, user_id: str, role: Role,
                        granted_by: str) -> None
    def can_user_edit(self, user_id: str, item_id: str) -> bool

    # Versioning
    def get_version_history(self, item_id: str, limit: int = 10) -> List[Version]
    def rollback_item(self, item_id: str, version_number: int) -> KnowledgeItem

    # Audit
    def get_audit_log(self, tenant_id: str, limit: int = 100) -> List[Dict[str, Any]]

Support Development

If you find this package useful, consider supporting development:

Your support helps fund development of the entire Socratic ecosystem.

Examples

See examples/ directory for complete examples:

  • 01_basic_usage.py - Basic CRUD operations
  • 02_access_control.py - Role-based permissions
  • 03_versioning.py - Version history and rollback
  • 04_rag_integration.py - Semantic search with RAG

Integrations

Openclaw

from socratic_knowledge.integrations.openclaw import SocraticKnowledgeSkill

skill = SocraticKnowledgeSkill(storage="sqlite")
result = skill.search(tenant_id="org1", query="LLM prompt engineering", top_k=5)

LangChain

from socratic_knowledge.integrations.langchain import SocraticKnowledgeTool

tool = SocraticKnowledgeTool(storage="sqlite", enable_rag=True)
results = tool.semantic_search(
    tenant_id="org1",
    query="How to fine-tune models?",
    top_k=5
)

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Testing

# Run tests
pytest

# With coverage
pytest --cov=src/socratic_knowledge

# Specific test file
pytest tests/unit/test_knowledge_item.py -v

Quality

# Format code
black src/ tests/ examples/

# Lint
ruff check src/ tests/ examples/

# Type check
mypy src/socratic_knowledge

License

MIT License - see LICENSE file for details.

Project Status

Version: 0.1.0 (MVP)

Statistics

  • Supported Python: 3.9, 3.10, 3.11, 3.12
  • CI/CD: GitHub Actions

Implementation Progress

  • Phase 1: Core Foundation ✅ Complete
  • Phase 2: Access Control & Versioning ✅ Complete
  • Phase 3: RAG Integration & Search ✅ Complete
  • Phase 4: Collaboration & Audit ✅ Complete
  • Phase 5: Integrations ✅ Complete
  • Phase 6: Polish & Documentation ✅ Complete

Support


Built with ❤️ by the Socratic Ecosystem


Origin

This package comes from the Socrates research prototype, which is not maintained as a product. Status: alpha. Written by Efthimios Angelopoulos with AI coding assistants (Claude Code); I design, review and test it. Contact: Hermes_creative@proton.me.

Use This Package Standalone:

pip install socratic-knowledge

Or As Part of Socrates Platform:

pip install socrates-ai  # the earlier research prototype that uses this package

Integration Example:

More Information:


Metadata

Release files for socratic-knowledge 0.1.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for socratic-knowledge 0.1.9
File Size Uploaded Provenance Actions
socratic_knowledge-0.1.9.tar.gz 22.6 kB Without provenance Details for socratic_knowledge-0.1.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for socratic-knowledge 0.1.9
File Interpreter ABI Platform Actions
socratic_knowledge-0.1.9-py3-none-any.whl Python 3 none any Details for socratic_knowledge-0.1.9-py3-none-any.whl

Total release size: 34.8 kB

Release files / socratic_knowledge-0.1.9.tar.gz

Download URL socratic_knowledge-0.1.9.tar.gz
Size 22.6 kB
Tags Source
SHA-256 checksum
How to use checksums
cdfd9ddb0a1fc69713cfecd0d1f6c10a26bbc66241c43e6d7df38cd8ab72ec2a
BLAKE2b-256 checksum
How to use checksums
6f6baffdf032a7d6789f1556e929f74c3bf7f4f987e5f92ceb64e5d257242da5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / socratic_knowledge-0.1.9-py3-none-any.whl

Download URL socratic_knowledge-0.1.9-py3-none-any.whl
Size 12.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d6bcfd1b6dc0bb58086f708d88ff268370d7483fbbea51d151871a24d0245879
BLAKE2b-256 checksum
How to use checksums
d0a1c9c4099bf45ed2aced1f9af06db4876875afde5ba88968de7cacb88051be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for socratic-knowledge 0.1.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page