Executive Summary

indianconstitution is a production-grade Python infrastructure package engineered for high-throughput, deterministic algorithmic analysis of the Constitution of India. It provides formalized programmatic representations of all 464 articles, 12 schedules, the Preamble, landmark Supreme Court precedent mappings, amendment timelines, fundamental rights/duties cross-references, and multilingual translations — up to and including the Constitution (One Hundred and Sixth Amendment) Act, 2023.

Designed to serve as a foundational corpus infrastructure for legal NLP, Retrieval-Augmented Generation (RAG) pipelines, and civic data science, the engine operates under strict CPU-only execution guarantees with zero required network calls or cloud API keys.

⚡ Algorithmic Complexity & Guarantees

💻 Hardware Requirements & CPU Constraints

indianconstitution strictly enforces hardware portability and zero-GPU execution dependencies:

• Runtime Target: Runs on commodity x86_64 and ARM64 single-core or multi-core CPU dev machines.
• Hardware Isolation: AI and semantic retrieval pipelines (indianconstitution[ai]) disable GPU acceleration paths (CUDA_VISIBLE_DEVICES="", torch.set_num_threads(...)) to guarantee deterministic offline CPU execution without GPU driver dependencies.
• Memory Overhead: Instance heap footprint remains under 15 MB RAM, enabling microservice, serverless (AWS Lambda, Google Cloud Run), and embedded CLI execution.

📐 System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Public API Layer                         │
│   get_article() · search() · fuzzy_search() · get_constitution()│
└───────────────────────────────┬─────────────────────────────────┘
                                │
               ┌────────────────▼────────────────┐
               │    Constitution  (engine.py)     │
               │  Lazy-loading · Singleton cache  │
               └──┬──────────────┬───────────────┘
                  │              │
     ┌────────────▼───┐  ┌───────▼───────────┐  ┌──────────────────┐
     │  SearchEngine  │  │  ConstitutionGraph │  │    Exporter      │
     │ (inverted idx) │  │  (NetworkX graph)  │  │ JSON · CSV · MD  │
     └────────────────┘  └────────────────────┘  └──────────────────┘
                  │              │
     ┌────────────▼──────────────▼──────────────────┐
     │            Pydantic v2 Data Models           │
     │   Article · Part · Schedule · SearchResult   │
     │   CaseLaw · AmendmentEvent · DutyCrossRef    │
     └──────────────────────┬───────────────────────┘
                            │
     ┌──────────────────────▼───────────────────────┐
     │         Custom Typed Exception Hierarchy     │
     │  IndianConstitutionError (BaseException)     │
     │  ├── ArticleNotFoundError                    │
     │  ├── CorpusIntegrityError                    │
     │  ├── InvalidAmendmentRangeError              │
     │  ├── DependencyMissingError                  │
     │  └── UnsupportedFormatError                  │
     └──────────────────────────────────────────────┘

🚀 Quickstart

Installation

# Core package (zero external runtime dependencies)
pip install indianconstitution

# With network analysis & data science utilities (NetworkX, pandas)
pip install "indianconstitution[data]"

# With offline CPU semantic embeddings (sentence-transformers)
pip install "indianconstitution[ai]"

# Full installation suite
pip install "indianconstitution[all]"

Deterministic Python Usage

>>> from indianconstitution import get_article, search, get_constitution

>>> # Type-safe article retrieval (O(1) lookup)
>>> article = get_article("21A")
>>> article.number
'21A'
>>> article.title
'Right to Education'

>>> # Sub-millisecond inverted posting-list search
>>> results = search("equality before law", limit=3)
>>> [r.number for r in results]
['14', '15']

>>> # Full Constitution engine instance
>>> const = get_constitution()
>>> len(const) > 0
True

🛡️ Formal Exception Invariants

The library enforces fail-fast error reporting through a strict exception hierarchy derived from IndianConstitutionError:

from indianconstitution import (
    Constitution,
    ArticleNotFoundError,
    InvalidAmendmentRangeError,
    UnsupportedFormatError,
)

const = Constitution()

# 1. Missing Article Access Guard
try:
    article = const.require_article("99999")
except ArticleNotFoundError as err:
    print(f"Article identifier missing: {err.article_number}")

# 2. Year Bound Invariant Check
try:
    diff = const.diff_amendment("21A", from_year=2026, to_year=2010)
except InvalidAmendmentRangeError as err:
    print(f"Invalid temporal range: {err.from_year} > {err.to_year}")

# 3. Export Specification Enforcement
try:
    const.export("unsupported_fmt", "output.dat")
except UnsupportedFormatError as err:
    print(f"Format rejected: {err.format_requested}")

📊 Empirical Performance

Empirical execution benchmarks gathered via python scripts/benchmark.py over 1,000 iterations on a single CPU core:

🛠️ Verification & Quality Assurance Matrix

Every code modification and mathematical claim is verifiable via standard verification targets:

# 1. Static code quality analysis (Ruff)
ruff check src/indianconstitution

# 2. Code formatting verification (Ruff)
ruff format --check src/indianconstitution

# 3. Strict static type safety analysis (Mypy --strict)
mypy src/indianconstitution

# 4. Property-based & unit test suite (>90% coverage enforcement)
pytest

# 5. SHA-256 data integrity & schema validation
python scripts/validate_corpus.py

# 6. Local CPU empirical benchmark suite
python scripts/benchmark.py

📜 Citation

If you incorporate indianconstitution into software systems, research papers, or legal informatics benchmarks, please cite:

@software{vikhram2026indianconstitution,
  author       = {S, Vikhram},
  title        = {{IndianConstitution: High-Performance Algorithmic Infrastructure
                   \& Deterministic Corpus Engine for the Constitution of India}},
  year         = {2026},
  version      = {1.5.1},
  publisher    = {PyPI},
  url          = {https://github.com/Vikhram-S/IndianConstitution},
  doi          = {10.5281/zenodo.18200429},
  license      = {Apache-2.0},
}

📄 License

Copyright © 2026 Vikhram S. Distributed under the terms of the Apache License 2.0. See LICENSE.