Metadata-Version: 2.4
Name: contextual-engine
Version: 0.9.1
Summary: Temporal-first local code memory for AI tools via MCP
Project-URL: Homepage, https://contextuallabs.dev
Project-URL: Documentation, https://contextuallabs.dev/docs
Project-URL: Repository, https://github.com/Contextual-Laboratory/Contextual-Labs/issues
Project-URL: Changelog, https://contextuallabs.dev/changelog
Author: Contextual Contributors
License: BUSINESS SOURCE LICENSE 1.1 
        
        ---
        
        PARAMETERS
        
        Licensor:             [AARJUN MAHULE]
        
        Licensed Work:        [CONTEXTUAL V0.1.0]
        The Licensed Work is (c) [2026] [AARJUN MAHULE]
        
        Additional Use Grant:
        Production Use is permitted solely for:
        
        * Individuals acting for personal, non-commercial purposes
        * Non-commercial projects
        * Organizations with fewer than [5] employees AND annual revenue below [500,000INR]
        
        All other Production Use requires a separate commercial license from the Licensor.
        
        Change Date:          [2030-06-01] (typically four years from first public release)
        
        Change License:       Apache License, Version 2.0
        
        Governing Law:        This License shall be governed by and construed in accordance
        with the laws of Republic of India.
        
        Contact:              [aarjun.mahule23@gmail.com]
        
        ---
        
        TERMS
        
        1. Grant of Rights
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, and redistribute the Licensed Work, in whole or in part, for non-production use.
        
        2. Definition of Production Use
        
        “Production Use” means any use of the Licensed Work in a live, operational,
        or business environment, including but not limited to:
        
        * Use in software-as-a-service (SaaS), platform-as-a-service (PaaS),
          or hosted environments
        * Internal business operations, tools, or workflows
        * Revenue-generating systems or services
        * Customer-facing applications or services
        * Any environment serving real users, customers, or organizational functions
        
        3. Restriction on Production Use
        
        You may not use the Licensed Work for Production Use except as expressly
        permitted under the Additional Use Grant or through a separate commercial
        license agreement with the Licensor.
        
        If your use exceeds the scope of the Additional Use Grant, you must obtain
        a commercial license from the Licensor or cease use immediately.
        
        4. Change License
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor grants you rights under the
        terms of the Change License. On such date, the rights granted under this
        License terminate and are replaced by the Change License.
        
        5. Version Scope
        
        This License applies separately to each version of the Licensed Work.
        Each version may have its own Change Date as specified by the Licensor.
        
        6. Redistribution and Attribution
        
        You must conspicuously display this License and retain all copyright,
        license notices, and attribution in any original or modified copies
        of the Licensed Work.
        
        7. Termination
        
        Any use of the Licensed Work in violation of this License will automatically
        terminate your rights under this License for the current and all other
        versions of the Licensed Work.
        
        8. Trademarks
        
        This License does not grant you any rights to use the Licensor’s trademarks,
        service marks, or logos, except as required for reasonable and customary use
        in describing the Licensed Work.
        
        9. Disclaimer of Warranty
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED
        ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
        
        10. Limitation of Liability
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
        LICENSOR 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 LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
        LICENSED WORK.
        
        11. Governing Law
        
        This License shall be governed by and construed in accordance with the laws
        of Republic of India, without regard to conflict of law principles.
        
        ---
License-File: LICENSE
Keywords: ai,code-search,developer-tools,embeddings,local-first,mcp,temporal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Indexing
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Requires-Dist: blake3>=0.4.1
Requires-Dist: docutils>=0.21
Requires-Dist: dulwich>=0.21
Requires-Dist: einops>=0.7
Requires-Dist: fastmcp<4,>=3.2
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: lancedb<0.31,>=0.26
Requires-Dist: markdown-it-py>=4.0
Requires-Dist: mdit-py-plugins
Requires-Dist: numpy>=1.26
Requires-Dist: opentelemetry-api>=1.24.0
Requires-Dist: opentelemetry-sdk>=1.24.0
Requires-Dist: pathspec>=0.10
Requires-Dist: platformdirs>=3.3
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pygit2>=1.15
Requires-Dist: python-frontmatter
Requires-Dist: rapidfuzz>=3
Requires-Dist: rich>=13.0
Requires-Dist: safetensors>=0.4.3
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: simsimd<6,>=3.9
Requires-Dist: starlette>=0.37
Requires-Dist: structlog>=25.4
Requires-Dist: tantivy>=0.20.1
Requires-Dist: tenacity>=8.0
Requires-Dist: tiktoken>=0.5
Requires-Dist: tokenizers<=0.23.0,>=0.19
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: torch>=2.2
Requires-Dist: transformers<4.60,>=4.40
Requires-Dist: tree-sitter-language-pack>=0.7.2
Requires-Dist: typer<1.0,>=0.9
Requires-Dist: uvicorn>=0.27
Requires-Dist: watchdog>=4.0
Provides-Extra: benchmark
Requires-Dist: coir-eval; extra == 'benchmark'
Requires-Dist: ranx>=0.3; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: mps
Requires-Dist: torch>=2.4.0; extra == 'mps'
Requires-Dist: torchvision>=0.19.0; extra == 'mps'
Provides-Extra: test
Requires-Dist: anyio[trio]>=4.3.0; extra == 'test'
Requires-Dist: freezegun>=1.5.0; extra == 'test'
Requires-Dist: hypothesis>=6.100.0; extra == 'test'
Requires-Dist: polyfactory>=2.16.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
Requires-Dist: pytest>=8.3.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# Contextual

**Local-first temporal semantic code memory engine for AI tools**

[![PyPI](https://img.shields.io/pypi/v/contextual-engine)](https://pypi.org/project/contextual-engine/)
[![License](https://img.shields.io/badge/license-BUSL%201.1-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)

## What is Contextual?

Contextual transforms code repositories into queryable, time-aware knowledge structures. Unlike traditional RAG systems that treat code as static documents, Contextual maintains full temporal awareness, structural understanding, and semantic relationships across your entire codebase.

**The Four-Way Wedge:**
- **Local-first** - Embedded storage, no cloud dependency
- **Bitemporal** - Tracks when facts were true AND when you learned them
- **Code-aware** - AST parsing, not just text chunking
- **Tool-agnostic** - MCP integration works with any AI IDE/chat client

## Features

- **Hybrid Search** - BM25 + vector embeddings with RRF fusion
- **Temporal Queries** - Time-travel through your codebase history
- **Knowledge Graph** - Entity-relationship triples with recursive traversal
- **GNN Enhancement** - Graph neural networks propagate semantic context
- **Docs Write** - AI-powered documentation updates with two-phase commit
- **Incremental Indexing** - Git-aware change detection, BLAKE3 content hashing

## Installation

```bash
pip install contextual-engine
```

## Quick Start

```bash
# Initialize project
contextual init /path/to/repo

# Index codebase
contextual index .

# Search
contextual search "authentication middleware"

# Start MCP server (for Claude Desktop, Cursor, etc.)
contextual serve
```

## MCP Integration

Add to your AI tool's MCP config:

```json
{
  "mcpServers": {
    "contextual": {
      "command": "contextual",
      "args": ["serve", "--project", "/path/to/repo"]
    }
  }
}
```

## Documentation

- [Architecture](docs/ARCHITECTURE.md) - System design across all layers
- [Technical Spec](docs/TECHNICAL_SPEC.md) - Implementation details
- [Project Phases](docs/PROJECT_PHASES.md) - Development roadmap
- [MCP Tools](docs/MCP_TOOLS.md) - Tool contracts and API

## License

Business Source License 1.1 (BUSL-1.1) — see [LICENSE](LICENSE) for the full
terms, including the Additional Use Grant and the Change Date / Change License.
