sibyl-core 0.2.0__tar.gz

sibyl_core-0.2.0/.gitignore

@@ -0,0 +1,89 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Node
+node_modules/
+
+# VitePress
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+coverage.xml
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Environment
+.env
+.env.local
+
+# Docker
+falkordb_data/
+
+# Kubernetes / Tilt
+infra/local/secrets.yaml
+.tiltbuild/
+tilt_modules/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+.serena
+.coverage.*
+
+# moon
+.moon/cache
+.moon/docker
+
+# Backups and database dumps
+backups/
+*.sql
+!docs/schemas/*.sql

sibyl_core-0.2.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: sibyl-core
+Version: 0.2.0
+Summary: Core library for Sibyl - domain models, graph operations, and knowledge retrieval
+Project-URL: Homepage, https://github.com/hyperb1iss/sibyl
+Project-URL: Repository, https://github.com/hyperb1iss/sibyl
+Author-email: Stefanie Jane <stef@hyperbliss.tech>
+License-Expression: Apache-2.0
+Keywords: ai-agents,collective-intelligence,graph-rag,knowledge-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: anyio>=4.0
+Requires-Dist: crawl4ai>=0.7.8
+Requires-Dist: graphiti-core[anthropic,falkordb]>=0.24
+Requires-Dist: httpx>=0.27
+Requires-Dist: mistune>=3.0
+Requires-Dist: passlib>=1.7
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyjwt>=2.10
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-louvain>=0.16
+Requires-Dist: structlog>=24.0
+Description-Content-Type: text/markdown
+
+# sibyl-core
+
+Core library for Sibyl — domain models, graph operations, retrieval algorithms, and tool
+implementations. Shared foundation for the API server and CLI.
+
+## Quick Reference
+
+```bash
+# Install
+uv add sibyl-core
+
+# Development
+moon run core:lint        # Ruff check
+moon run core:typecheck   # Pyright
+moon run core:test        # Pytest
+```
+
+## What's Here
+
+- **models/** — Domain entities (Task, Project, Epic, Agent, Source, etc.)
+- **graph/** — FalkorDB/Graphiti client, entity management
+- **retrieval/** — Hybrid search (semantic + BM25), fusion, deduplication
+- **tools/** — MCP tool implementations (search, explore, add, manage)
+- **tasks/** — Workflow engine, dependency resolution
+- **auth/** — JWT primitives, password hashing
+
+## Structure
+
+```
+src/sibyl_core/
+├── models/
+│   ├── entities.py       # Entity, EntityType, base classes
+│   ├── tasks.py          # Task, Project, Epic, Milestone
+│   ├── agents.py         # AgentRecord, WorktreeRecord, ApprovalRecord, Checkpoint
+│   ├── sources.py        # Source, Document
+│   └── responses.py      # API response models
+├── graph/
+│   ├── client.py         # GraphClient (connection, write lock)
+│   ├── entities.py       # EntityManager (CRUD, search)
+│   └── relationships.py  # RelationshipManager
+├── retrieval/
+│   ├── hybrid.py         # Hybrid search orchestration
+│   └── fusion.py         # Score fusion (RRF)
+├── tools/
+│   ├── search.py         # Semantic search
+│   ├── explore.py        # Graph navigation
+│   ├── add.py            # Entity creation
+│   └── manage.py         # Task workflow, admin
+└── tasks/
+    ├── workflow.py       # State machine, transitions
+    └── manager.py        # Task operations
+```
+
+## Usage
+
+### Models
+
+```python
+from sibyl_core.models import (
+    Entity, EntityType, Task, TaskStatus, Project, Epic,
+    AgentRecord, AgentStatus, WorktreeRecord, ApprovalRecord,
+)
+
+task = Task(
+    name="Implement OAuth",
+    content="Add Google and GitHub OAuth",
+    project_id="proj_abc",
+    status=TaskStatus.TODO,
+)
+```
+
+### Agent Models
+
+```python
+from sibyl_core.models import (
+    AgentRecord, AgentStatus, AgentType,
+    WorktreeRecord, WorktreeStatus,
+    ApprovalRecord, ApprovalType, ApprovalStatus,
+    AgentCheckpoint,
+)
+
+# Agent record (persistent state)
+agent = AgentRecord(
+    name="OAuth Implementation Agent",
+    status=AgentStatus.WORKING,
+    agent_type=AgentType.IMPLEMENTER,
+    task_id="task_abc",
+    tokens_used=15000,
+    cost_usd=0.45,
+)
+
+# Git worktree for isolation
+worktree = WorktreeRecord(
+    agent_id="agent_xyz",
+    path="/worktrees/agent-xyz",
+    branch="agent/oauth-impl",
+    status=WorktreeStatus.ACTIVE,
+)
+
+# Human-in-the-loop approval
+approval = ApprovalRecord(
+    agent_id="agent_xyz",
+    approval_type=ApprovalType.FILE_WRITE,
+    summary="Write to config.py",
+    status=ApprovalStatus.PENDING,
+)
+
+# Session checkpoint for resume
+checkpoint = AgentCheckpoint(
+    agent_id="agent_xyz",
+    session_id="sess_123",
+    conversation_summary="Implementing OAuth...",
+    current_step="Writing auth module",
+)
+```
+
+### Graph Client
+
+```python
+from sibyl_core.graph import GraphClient, EntityManager
+
+client = await GraphClient.create()
+manager = EntityManager(client, group_id=str(org_id))
+
+# CRUD
+await manager.create(entity)
+entity = await manager.get_by_id("entity_abc")
+results = await manager.search("authentication patterns", limit=20)
+```
+
+### Write Concurrency
+
+All writes use the write lock to prevent FalkorDB corruption:
+
+```python
+async with client.write_lock:
+    await client.execute_write_org(org_id, query, **params)
+
+# Or use EntityManager (handles locking internally)
+await manager.create(entity)
+```
+
+### Task Workflow
+
+```python
+from sibyl_core.tasks import TaskManager
+
+manager = TaskManager(entity_manager)
+await manager.start_task(task_id)
+await manager.complete_task(task_id, learnings="Key insight...")
+await manager.block_task(task_id, reason="Waiting on API")
+```
+
+## Entity Types
+
+| Type | Description |
+|------|-------------|
+| `pattern` | Reusable coding patterns |
+| `episode` | Temporal learnings |
+| `task` | Work items with workflow |
+| `project` | Container for tasks |
+| `epic` | Feature-level grouping |
+| `source` | Documentation sources |
+| `document` | Crawled content |
+| `agent` | AI agent records |
+| `worktree` | Git worktree isolation |
+| `approval` | Human approval requests |
+| `checkpoint` | Agent session state |
+
+## Relationship Types
+
+```python
+from sibyl_core.models import RelationshipType
+
+# Knowledge
+RelationshipType.APPLIES_TO, REQUIRES, CONFLICTS_WITH, SUPERSEDES
+
+# Task
+RelationshipType.BELONGS_TO, DEPENDS_ON, BLOCKS, REFERENCES
+
+# Agent
+RelationshipType.WORKS_ON, USES_WORKTREE, CHECKPOINTED_AS, REQUESTED_BY
+```
+
+## Configuration
+
+```bash
+SIBYL_OPENAI_API_KEY=sk-...         # Required (embeddings)
+SIBYL_FALKORDB_HOST=localhost
+SIBYL_FALKORDB_PORT=6380
+SIBYL_ANTHROPIC_API_KEY=...         # Optional (agents)
+```
+
+## Key Patterns
+
+**Multi-tenancy:** Every operation requires org context
+```python
+manager = EntityManager(client, group_id=str(org.id))
+```
+
+**Node labels:** Graphiti creates `Episodic` and `Entity` nodes
+```cypher
+WHERE (n:Episodic OR n:Entity) AND n.entity_type = $type
+```
+
+**Creation paths:** LLM-powered (`create`) vs direct (`create_direct`)
+```python
+await manager.create(entity)         # Slower, richer extraction
+await manager.create_direct(entity)  # Faster, no LLM
+```
+
+## Testing
+
+```bash
+# With mock LLM (fast, deterministic)
+SIBYL_MOCK_LLM=true uv run pytest tests/
+
+# Live model tests (costs money)
+uv run pytest tests/live --live-models
+```

sibyl_core-0.2.0/README.md

@@ -0,0 +1,220 @@
+# sibyl-core
+
+Core library for Sibyl — domain models, graph operations, retrieval algorithms, and tool
+implementations. Shared foundation for the API server and CLI.
+
+## Quick Reference
+
+```bash
+# Install
+uv add sibyl-core
+
+# Development
+moon run core:lint        # Ruff check
+moon run core:typecheck   # Pyright
+moon run core:test        # Pytest
+```
+
+## What's Here
+
+- **models/** — Domain entities (Task, Project, Epic, Agent, Source, etc.)
+- **graph/** — FalkorDB/Graphiti client, entity management
+- **retrieval/** — Hybrid search (semantic + BM25), fusion, deduplication
+- **tools/** — MCP tool implementations (search, explore, add, manage)
+- **tasks/** — Workflow engine, dependency resolution
+- **auth/** — JWT primitives, password hashing
+
+## Structure
+
+```
+src/sibyl_core/
+├── models/
+│   ├── entities.py       # Entity, EntityType, base classes
+│   ├── tasks.py          # Task, Project, Epic, Milestone
+│   ├── agents.py         # AgentRecord, WorktreeRecord, ApprovalRecord, Checkpoint
+│   ├── sources.py        # Source, Document
+│   └── responses.py      # API response models
+├── graph/
+│   ├── client.py         # GraphClient (connection, write lock)
+│   ├── entities.py       # EntityManager (CRUD, search)
+│   └── relationships.py  # RelationshipManager
+├── retrieval/
+│   ├── hybrid.py         # Hybrid search orchestration
+│   └── fusion.py         # Score fusion (RRF)
+├── tools/
+│   ├── search.py         # Semantic search
+│   ├── explore.py        # Graph navigation
+│   ├── add.py            # Entity creation
+│   └── manage.py         # Task workflow, admin
+└── tasks/
+    ├── workflow.py       # State machine, transitions
+    └── manager.py        # Task operations
+```
+
+## Usage
+
+### Models
+
+```python
+from sibyl_core.models import (
+    Entity, EntityType, Task, TaskStatus, Project, Epic,
+    AgentRecord, AgentStatus, WorktreeRecord, ApprovalRecord,
+)
+
+task = Task(
+    name="Implement OAuth",
+    content="Add Google and GitHub OAuth",
+    project_id="proj_abc",
+    status=TaskStatus.TODO,
+)
+```
+
+### Agent Models
+
+```python
+from sibyl_core.models import (
+    AgentRecord, AgentStatus, AgentType,
+    WorktreeRecord, WorktreeStatus,
+    ApprovalRecord, ApprovalType, ApprovalStatus,
+    AgentCheckpoint,
+)
+
+# Agent record (persistent state)
+agent = AgentRecord(
+    name="OAuth Implementation Agent",
+    status=AgentStatus.WORKING,
+    agent_type=AgentType.IMPLEMENTER,
+    task_id="task_abc",
+    tokens_used=15000,
+    cost_usd=0.45,
+)
+
+# Git worktree for isolation
+worktree = WorktreeRecord(
+    agent_id="agent_xyz",
+    path="/worktrees/agent-xyz",
+    branch="agent/oauth-impl",
+    status=WorktreeStatus.ACTIVE,
+)
+
+# Human-in-the-loop approval
+approval = ApprovalRecord(
+    agent_id="agent_xyz",
+    approval_type=ApprovalType.FILE_WRITE,
+    summary="Write to config.py",
+    status=ApprovalStatus.PENDING,
+)
+
+# Session checkpoint for resume
+checkpoint = AgentCheckpoint(
+    agent_id="agent_xyz",
+    session_id="sess_123",
+    conversation_summary="Implementing OAuth...",
+    current_step="Writing auth module",
+)
+```
+
+### Graph Client
+
+```python
+from sibyl_core.graph import GraphClient, EntityManager
+
+client = await GraphClient.create()
+manager = EntityManager(client, group_id=str(org_id))
+
+# CRUD
+await manager.create(entity)
+entity = await manager.get_by_id("entity_abc")
+results = await manager.search("authentication patterns", limit=20)
+```
+
+### Write Concurrency
+
+All writes use the write lock to prevent FalkorDB corruption:
+
+```python
+async with client.write_lock:
+    await client.execute_write_org(org_id, query, **params)
+
+# Or use EntityManager (handles locking internally)
+await manager.create(entity)
+```
+
+### Task Workflow
+
+```python
+from sibyl_core.tasks import TaskManager
+
+manager = TaskManager(entity_manager)
+await manager.start_task(task_id)
+await manager.complete_task(task_id, learnings="Key insight...")
+await manager.block_task(task_id, reason="Waiting on API")
+```
+
+## Entity Types
+
+| Type | Description |
+|------|-------------|
+| `pattern` | Reusable coding patterns |
+| `episode` | Temporal learnings |
+| `task` | Work items with workflow |
+| `project` | Container for tasks |
+| `epic` | Feature-level grouping |
+| `source` | Documentation sources |
+| `document` | Crawled content |
+| `agent` | AI agent records |
+| `worktree` | Git worktree isolation |
+| `approval` | Human approval requests |
+| `checkpoint` | Agent session state |
+
+## Relationship Types
+
+```python
+from sibyl_core.models import RelationshipType
+
+# Knowledge
+RelationshipType.APPLIES_TO, REQUIRES, CONFLICTS_WITH, SUPERSEDES
+
+# Task
+RelationshipType.BELONGS_TO, DEPENDS_ON, BLOCKS, REFERENCES
+
+# Agent
+RelationshipType.WORKS_ON, USES_WORKTREE, CHECKPOINTED_AS, REQUESTED_BY
+```
+
+## Configuration
+
+```bash
+SIBYL_OPENAI_API_KEY=sk-...         # Required (embeddings)
+SIBYL_FALKORDB_HOST=localhost
+SIBYL_FALKORDB_PORT=6380
+SIBYL_ANTHROPIC_API_KEY=...         # Optional (agents)
+```
+
+## Key Patterns
+
+**Multi-tenancy:** Every operation requires org context
+```python
+manager = EntityManager(client, group_id=str(org.id))
+```
+
+**Node labels:** Graphiti creates `Episodic` and `Entity` nodes
+```cypher
+WHERE (n:Episodic OR n:Entity) AND n.entity_type = $type
+```
+
+**Creation paths:** LLM-powered (`create`) vs direct (`create_direct`)
+```python
+await manager.create(entity)         # Slower, richer extraction
+await manager.create_direct(entity)  # Faster, no LLM
+```
+
+## Testing
+
+```bash
+# With mock LLM (fast, deterministic)
+SIBYL_MOCK_LLM=true uv run pytest tests/
+
+# Live model tests (costs money)
+uv run pytest tests/live --live-models
+```

sibyl_core-0.2.0/pyproject.toml

@@ -0,0 +1,91 @@
+# sibyl-core - Shared library for Sibyl knowledge graph operations
+# Domain models, graph client, retrieval, tools, auth primitives
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "../../../VERSION"
+pattern = "(?P<version>.+)"
+
+[project]
+name = "sibyl-core"
+dynamic = ["version"]
+description = "Core library for Sibyl - domain models, graph operations, and knowledge retrieval"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Stefanie Jane", email = "stef@hyperbliss.tech" }]
+keywords = ["ai-agents", "knowledge-graph", "graph-rag", "collective-intelligence"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    # Knowledge Graph
+    "graphiti-core[falkordb,anthropic]>=0.24",
+    # Data & Validation
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    # Auth primitives (JWT, password hashing)
+    "passlib>=1.7",
+    "pyjwt>=2.10",
+    # Async & HTTP
+    "anyio>=4.0",
+    "httpx>=0.27",
+    # Logging
+    "structlog>=24.0",
+    # Environment
+    "python-dotenv>=1.0",
+    # Content processing
+    "crawl4ai>=0.7.8",
+    "mistune>=3.0",
+    # Graph analysis
+    "python-louvain>=0.16",
+]
+
+[dependency-groups]
+dev = [
+    "pyright",
+    "pytest",
+    "pytest-asyncio",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://github.com/hyperb1iss/sibyl"
+Repository = "https://github.com/hyperb1iss/sibyl"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sibyl_core"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sibyl_core"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.13"
+typeCheckingMode = "standard"
+
+# =============================================================================
+# UV Workspace (inherits from root)
+# =============================================================================
+# This package is part of the sibyl-workspace
+# Dependencies on other workspace members use workspace = true

sibyl_core-0.2.0/src/sibyl_core/__init__.py

@@ -0,0 +1,46 @@
+"""
+sibyl-core: Core library for Sibyl knowledge graph operations.
+
+This package provides:
+- Domain models (Entity, Task, Project, etc.)
+- Graph client and entity management (FalkorDB/Graphiti)
+- Hybrid retrieval (semantic + keyword search)
+- Core tools (search, explore, add)
+- Task workflow engine
+- Auth primitives (JWT, password hashing)
+"""
+
+from sibyl_core._version import __version__, get_version
+from sibyl_core.config import CoreConfig, core_config
+from sibyl_core.errors import (
+    ConventionsMCPError,
+    EntityCreationError,
+    EntityNotFoundError,
+    GraphConnectionError,
+    GraphError,
+    IngestionError,
+    InvalidTransitionError,
+    SearchError,
+    SibylError,
+    ValidationError,
+)
+
+__all__ = [
+    # Errors
+    "ConventionsMCPError",
+    # Config
+    "CoreConfig",
+    "EntityCreationError",
+    "EntityNotFoundError",
+    "GraphConnectionError",
+    "GraphError",
+    "IngestionError",
+    "InvalidTransitionError",
+    "SearchError",
+    "SibylError",
+    "ValidationError",
+    # Version
+    "__version__",
+    "core_config",
+    "get_version",
+]