sahara-memory 0.2.1__tar.gz

sahara_memory-0.2.1/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.tox/
+
+# macOS
+.DS_Store
+.AppleDouble
+._*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment / secrets
+.env
+.env.local
+.env.*.local
+
+# Sahara runtime files (not source)
+*.db
+*.db-wal
+*.db-shm

sahara_memory-0.2.1/.saharaignore.template

@@ -0,0 +1,123 @@
+# .saharaignore — Sahara ignore rules
+#
+# Syntax is identical to .gitignore (gitignore wildmatch patterns).
+# Lines beginning with # are comments.
+# Blank lines are ignored.
+#
+# Patterns are evaluated relative to the indexed content root.
+#
+# Examples:
+#   *.log            — ignore all .log files anywhere
+#   /tmp/            — ignore the "tmp" folder at the root of the content root
+#   build/           — ignore any folder named "build"
+#   docs/**/*.pdf    — ignore all PDFs inside docs/ recursively
+#   !important.log   — un-ignore important.log (exception to a broader rule)
+#
+# ──────────────────────────────────────────────────────────────────────────────
+# Version control
+# ──────────────────────────────────────────────────────────────────────────────
+.git/
+.hg/
+.svn/
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Python
+# ──────────────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+.env/
+env/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# ──────────────────────────────────────────────────────────────────────────────
+# JavaScript / Node
+# ──────────────────────────────────────────────────────────────────────────────
+node_modules/
+.npm/
+.yarn/
+.pnp.*
+
+# ──────────────────────────────────────────────────────────────────────────────
+# macOS
+# ──────────────────────────────────────────────────────────────────────────────
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
+Icon
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Windows
+# ──────────────────────────────────────────────────────────────────────────────
+Thumbs.db
+Desktop.ini
+ehthumbs.db
+$RECYCLE.BIN/
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Linux
+# ──────────────────────────────────────────────────────────────────────────────
+*~
+.directory
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Editors
+# ──────────────────────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+*.bak
+*.orig
+*.tmp
+*_conflict-*
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Logs and databases
+# ──────────────────────────────────────────────────────────────────────────────
+*.log
+*.sqlite
+*.sqlite3
+*.db
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Archives (comment out if you want to sync zip files)
+# ──────────────────────────────────────────────────────────────────────────────
+# *.zip
+# *.tar
+# *.tar.gz
+# *.tar.bz2
+# *.7z
+# *.rar
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Secrets (HIGHLY RECOMMENDED to keep these ignored)
+# ──────────────────────────────────────────────────────────────────────────────
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials/
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Sahara internals (do not remove)
+# ──────────────────────────────────────────────────────────────────────────────
+.sahara/
+.saharaignore
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Add your custom rules below this line
+# ──────────────────────────────────────────────────────────────────────────────

sahara_memory-0.2.1/ARCHITECTURE.md

@@ -0,0 +1,256 @@
+# Sahara — Architecture
+
+This document explains how Sahara is structured so contributors can find their way around quickly and extend the system without touching unrelated code.
+
+---
+
+## System overview
+
+```
+┌─────────────┐   ┌────────────────┐   ┌──────────────────────┐
+│ CLI (click) │──▶│ IndexingService│──▶│ SearchEngine         │
+│ cli.py      │   │ library.py     │   │ fastembed + vec      │
+└─────────────┘   └────────────────┘   └──────────────────────┘
+       │                   │                      │
+       │                   ▼                      ▼
+       │             ┌──────────┐             AskEngine
+       │             │ StateDB  │             Ollama/OpenAI
+       │             └──────────┘
+       │                   ▲
+       ▼                   │
+┌─────────────┐   ┌──────────────────────┐
+│ SyncEngine  │──▶│ Optional StorageBackend│
+└─────────────┘   │ S3 / LocalDrive      │
+                  └──────────────────────┘
+```
+
+The CLI is the only public surface. Everything else is an internal library that the CLI composes.
+
+---
+
+## Source layout
+
+```
+src/sahara/
+├── cli.py                  # All Click commands — the public API
+├── config.py               # SaharaConfig dataclass + TOML I/O
+├── library.py              # Content-root migration and local indexing service
+├── models.py               # FileRecord, SyncOperation, ManifestEntry, ...
+│
+├── storage/
+│   ├── backend.py          # StorageBackend Protocol (the interface)
+│   ├── s3_client.py        # AWS S3 + MinIO implementation
+│   ├── local_drive_client.py  # Local filesystem implementation
+│   ├── dual_write_backend.py  # local+glacier dual-write wrapper
+│   ├── state_db.py         # SQLite state — files, history, chunks, ...
+│   └── cost_estimator.py   # S3 pricing estimates
+│
+├── sync/
+│   ├── sync_engine.py      # Three-way diff, conflict resolution, execution
+│   ├── daemon.py           # Background sync loop
+│   ├── file_watcher.py     # watchdog integration
+│   └── ignore_rules.py     # .saharaignore parser
+│
+├── search/
+│   ├── search_engine.py    # Text extraction, chunking, embedding, sqlite-vec KNN
+│   └── ask_engine.py       # LLM answer generation (ollama / OpenAI)
+│
+└── utils/
+    ├── encryption.py       # AES-256-GCM, PBKDF2, keyring
+    ├── hash.py             # SHA-256 helpers (shared between sync and search)
+    └── notifier.py         # OS desktop notification
+```
+
+---
+
+## Storage backends
+
+### The `StorageBackend` Protocol
+
+`src/sahara/storage/backend.py` defines the `StorageBackend` Protocol. Every backend must implement these methods:
+
+| Method | Purpose |
+|--------|---------|
+| `upload_file` | Upload a local file, optionally encrypting it first |
+| `download_file` | Download a key to a local path, optionally decrypting |
+| `delete_object` | Delete a key |
+| `copy_object` | Copy within the same backend (rename path) |
+| `get_manifest` / `put_manifest` | Fetch / write the Sahara manifest atomically |
+| `list_all_objects` | Bootstrap when no manifest exists yet |
+| `head_object` | Return metadata (size, etag, storage class) |
+| `validate_bucket_access` | Connectivity check |
+| `check_conditional_put_support` | Whether atomic manifest writes are supported |
+| `restore_object` | Glacier restore (S3 only; raise if unsupported) |
+
+`SyncEngine` accepts any `StorageBackend` — it never imports a concrete backend class directly.
+
+### Adding a new backend
+
+1. Create `src/sahara/storage/mybackend_client.py`
+2. Implement all methods in the `StorageBackend` Protocol (use `LocalDriveClient` as the simplest reference)
+3. Add an `isinstance` check in `cli.py` where the backend is instantiated (search for `storage_mode`)
+4. Add tests in `tests/test_mybackend.py` — mock the external service, do not require real network access
+
+### Current backends
+
+| Class | Module | Description |
+|-------|--------|-------------|
+| `S3Client` | `storage/s3_client.py` | AWS S3 and MinIO (via `endpoint_url`) |
+| `LocalDriveClient` | `storage/local_drive_client.py` | Local filesystem or network mount |
+| `DualWriteBackend` | `storage/dual_write_backend.py` | Writes to two backends simultaneously (local + glacier) |
+
+---
+
+## Sync pipeline
+
+The sync pipeline lives in `sync/sync_engine.py`. The sequence for a full sync:
+
+```
+1. Load manifest from storage (single JSON object — avoids per-file HeadObject calls)
+2. Scan local folder → build local snapshot {path → sha256}
+3. Load last-known-good state from StateDB
+4. Three-way diff(local, remote_manifest, last_known_good):
+     - New local file  → upload
+     - Deleted locally → delete from remote (or skip if remote was also changed = conflict)
+     - New remote file → download
+     - Deleted remotely → delete locally
+     - Both modified   → conflict
+5. For each operation: execute in thread pool (max_workers parallel)
+6. Write updated manifest back to storage (atomic via If-Match ETag check)
+7. Update StateDB with new sync state
+```
+
+### Why the manifest?
+
+Without the manifest, every sync would need to call `HeadObject` on every file in the bucket to check its current state — at $0.0004 per 1,000 calls and 50k files, that is $0.02 per sync, $7/month. The manifest is a single JSON blob stored at `.sahara/manifest.json` in the bucket. One `GetObject` replaces thousands of `HeadObject` calls.
+
+### Conflict resolution
+
+Conflict strategy is set in config (`backup` / `local` / `remote` / `ask`). The `backup` strategy (default) renames the local copy to `filename.conflict-TIMESTAMP.ext` and downloads the remote version — no data loss.
+
+---
+
+## Search pipeline
+
+The search pipeline runs entirely locally. `library.py` scans every registered content
+root directly; it does not depend on sync records or a storage backend.
+
+```
+1. IndexingService.index():
+   a. Load content roots from StateDB
+   b. Walk each root with .saharaignore rules
+   c. Maintain index_entries inventory and detect missing files
+   d. Call SearchEngine for supported local files
+
+2. SearchEngine.index_file(path):
+   a. Extract text (TextExtractor) — supports .txt, .md, .py, .pdf, .docx, and plain-text heuristic
+   b. Chunk text: 1600-char chunks with 320-char overlap
+   c. Embed each chunk independently with BAAI/bge-small-en-v1.5 (384-dim) via fastembed
+   d. Insert rows into `chunks` table and `vec_chunks` virtual table (sqlite-vec)
+
+3. search(query):
+   a. Embed the query string
+   b. KNN query against vec_chunks (O(log n) ANN, not a Python cosine loop)
+   c. Join against `chunks` to get file paths and snippet text
+   d. Deduplicate: keep best chunk score per file
+   e. Return ranked list of {relative_path, score, snippet}
+```
+
+### Why chunked indexing?
+
+A 50-page PDF has ~25,000 words. Embedding the whole document as one vector would mean the embedding averages over all content, making any specific detail on page 30 nearly unretrievable. By splitting into 400-token chunks with 80-token overlap, each chunk can be matched independently, so a query about page 30 will find the right chunk.
+
+### Adding a new file parser
+
+`TextExtractor.extract()` in `search/search_engine.py` dispatches on file extension. Add a new `elif suffix == ".xyz"` branch there. For heavier parsers (OCR, audio transcription) consider wrapping the import in a `try/except ImportError` so the base install does not require the dependency.
+
+---
+
+## Ask pipeline
+
+`search/ask_engine.py` wraps `SearchEngine` with an LLM layer.
+
+```
+1. Run search(question, top_k)
+2. Build context string from top chunk texts (capped at 6,000 chars)
+3. Try LLM in priority order:
+   a. OpenAI if OPENAI_API_KEY is set
+   b. Ollama at http://localhost:11434 if reachable
+   c. Degrade: return search results with snippets, no generated answer
+4. Return AskResult(answer, sources, degraded, model_used)
+```
+
+Degraded mode is intentional — `sahara ask` is useful even without any LLM installed, because the ranked snippets alone often answer the question visually.
+
+---
+
+## Daemon and file watcher
+
+`sync/daemon.py` runs a background loop that calls `SyncEngine.sync()` on a configurable interval. `sync/file_watcher.py` wraps watchdog's `Observer` and triggers an immediate partial sync when specific files change, rather than waiting for the interval.
+
+The daemon writes a PID file to `~/.sahara/daemon.pid` and logs to `~/.sahara/daemon.log`. The CLI's `sahara daemon start/stop/status` commands manage it.
+
+---
+
+## SQLite schema
+
+All state is stored in `~/.sahara/state.db`. WAL mode is enabled on every connection for safe concurrent reads.
+
+| Table | Purpose |
+|-------|---------|
+| `files` | One row per synced file — sha256, size, tier, timestamps, is_deleted |
+| `history` | Append-only log of every sync operation |
+| `pending_multipart` | In-flight multipart upload state (crash recovery) |
+| `sync_targets` | Registered (local_path, s3_prefix) pairs |
+| `content_roots` | Canonical indexed folders with primary and sync-enabled flags |
+| `index_entries` | Local indexing inventory and indexed/unsupported/missing status |
+| `storage_residency` | Explicit present/offloaded/missing state for stored files |
+| `config_kv` | Key-value store for runtime config values |
+| `embeddings` | Legacy single-vector-per-file index (superseded by `chunks`) |
+| `chunks` | One row per text chunk — path, chunk_index, content_hash, chunk_text |
+| `vec_chunks` | sqlite-vec virtual table — one float[384] vector per chunk (rowid matches `chunks.id`) |
+
+The `chunks` and `vec_chunks` tables work as a pair. `vec_chunks` stores the raw vectors; `chunks` stores the text and metadata. A JOIN on `rowid = id` links them.
+
+### Offload lifecycle
+
+`StorageLifecycle.offload()` requires a synced, indexed file. It downloads the stored
+object to temporary storage, decrypts it when needed, verifies the plaintext SHA-256,
+marks the file offloaded, and then removes the local source. Chunks and embeddings are
+retained. `fetch()` downloads atomically, verifies the same checksum, and marks the file
+present again. Sync ignores intentional offloads so they cannot be mistaken for local
+deletions.
+
+---
+
+## Configuration
+
+Config lives at `~/.sahara/config.toml`. `storage_mode = "none"` is the fresh-install
+default. Existing configuration files that predate `storage_mode` are loaded as S3
+configurations for compatibility. The CLI reads configuration at startup and passes a
+snapshot down to each subsystem.
+
+The TOML format is stable and user-editable. Do not add auto-generated comments or machine-managed sections to the config file.
+
+---
+
+## Known limitations
+
+- **No reranker yet.** Results from sqlite-vec KNN are re-sorted by score but not re-ranked by a cross-encoder. Precision is good but not state-of-the-art for ambiguous queries.
+- **Single embedding model.** Only `BAAI/bge-small-en-v1.5` (384-dim) is supported. Switching models requires re-indexing all files.
+- **No incremental re-indexing.** `sahara index` re-indexes the whole collection. Content-hash tracking means only changed files are re-embedded, but the check is O(n) on the files table.
+- **Single-user only.** The manifest + SQLite architecture assumes one writer at a time. Multiple machines syncing to the same bucket will serialize through the manifest ETag check.
+
+---
+
+## Where to start
+
+| Contribution area | Start here |
+|-------------------|-----------|
+| New storage backend | `storage/backend.py` (Protocol) → `storage/local_drive_client.py` (simplest impl) |
+| New file parser | `search/search_engine.py` `TextExtractor.extract()` |
+| Improve search ranking | `search/search_engine.py` `SearchEngine.search()` |
+| New CLI command | `cli.py` — add a `@main.command()` function |
+| Sync bug | `sync/sync_engine.py` `DiffResult` and `_execute_operations()` |
+| Daemon / watcher | `sync/daemon.py`, `sync/file_watcher.py` |
+| Encryption | `utils/encryption.py` |

sahara_memory-0.2.1/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to Sahara are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Sahara uses [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.2.1] — 2026-06-07
+
+### Added
+
+- Trusted Publishing workflows for verified TestPyPI and PyPI releases
+- Contributor Covenant 3.0 code of conduct with private incident reporting
+- Claude Desktop launch guide with platform configuration, exact MCP tool contracts,
+  security boundaries, verification, and troubleshooting
+- Three-step product plan for basic indexing with optional local-drive or AWS storage
+- Basic index-only mode with non-interactive `sahara init --mode basic --folder <path>`
+- Canonical content-root and index-inventory database tables
+- `sahara folder add/list/remove/sync` commands for index and sync scope management
+- `sahara storage configure local/aws` for upgrading an existing basic library
+- Checksum-verified `sahara offload` and `sahara fetch` with retained search metadata
+- Explicit storage residency in CLI search/list/status and MCP results
+- Local indexing that scans content roots without requiring sync records or storage
+- `sahara mcp install-claude` for merge-safe, one-command Claude Desktop setup on
+  macOS and Windows
+
+### Changed
+
+- Restored full mypy checking for the daemon and filesystem watcher
+- Renamed the Python distribution from `sahara` to `sahara-memory` to avoid the
+  unrelated OpenStack Sahara project on PyPI; the product name, `sahara` CLI,
+  and `sahara` import package are unchanged
+- First-time indexing now explains the local embedding-model download and clarifies
+  that Hugging Face authentication warnings do not require user action
+- Package and license metadata now identify Nidheesh Puthalath as the maintainer
+- README quick start now demonstrates both CLI retrieval and cited Claude Desktop use
+- Added fictional, privacy-safe README, social, and reproducible terminal demo assets
+- Ollama is the initial answer provider; OpenAI can be selected explicitly or saved
+  as the user's default without installing Ollama
+- Added first-run Ollama and optional OpenAI setup guidance
+- Streamlined the README around local search first, with answers, MCP, and storage
+  introduced as optional extensions
+- Added a categorized reference covering every CLI command
+- Documentation consolidated around current user, contributor, release, and architecture
+  guidance; superseded specifications remain available through Git history
+- Fresh installations default to local indexing; legacy configs without `storage_mode`
+  retain their previous S3 behavior
+- `index-report` now reads the local index inventory rather than the sync file table
+
+---
+
+## [0.2.0] — 2026-06-06
+
+### Added
+
+- **Semantic search** — `sahara index` extracts and embeds file content; `sahara search <query>` retrieves files by meaning using sqlite-vec KNN
+- **Chunked indexing** — long documents (PDFs, DOCX) are split into overlapping 400-token chunks so content past the first page is retrievable
+- **`sahara ask`** — natural language question answering; uses local Ollama or OpenAI when available, degrades gracefully to ranked snippets
+- **MinIO backend** — S3-compatible self-hosted storage via `endpoint_url` configuration
+- **Local drive backend** — sync to a second local drive or NAS with no cloud account required
+- **`local+glacier` dual-write mode** — writes to a local drive and S3 Glacier simultaneously
+- **`StorageBackend` Protocol** — formal structural interface for all storage backends; `SyncEngine` no longer imports concrete backend classes
+- **`BAAI/bge-small-en-v1.5` embedding model** — 384-dim vectors via `fastembed`; fast enough for CPU-only indexing
+- **PDF and DOCX extraction** — `pypdf` and `python-docx` are optional dependencies under `[search]`
+- **`sahara doctor --repair`** — diagnose and auto-fix common configuration problems
+- **SHA-256 utility** — shared `utils/hash.py` used by both sync and search (previously duplicated)
+- **Read-only MCP server** — exposes search, ask, chunk reads, folder listing, and index status to Claude Desktop and other MCP clients
+- **Authenticated remote MCP** — HTTP/streamable transport with bearer-token protection for secure tunnel and remote-client workflows
+- **MCP exposure controls** — tool and storage-prefix allowlists, snippet-size limits, and warnings for non-loopback bindings
+- **`sahara index-report`** — reports indexed/unindexed file counts, skip reasons, and sample indexing gaps
+- **MIT license file** — included in the repository, wheel metadata, and source distribution
+
+### Changed
+
+- Public positioning updated to "Sahara: extended storage, searchable memory and instant retrieval"
+- `_require_config` guard: local drive mode no longer requires a bucket to be configured
+- Storage modules reorganised into `src/sahara/storage/`, sync modules into `src/sahara/sync/`
+- Indexing skips unsupported binary media instead of attempting noisy text extraction
+
+### Fixed
+
+- Manifest locking race condition under concurrent syncs
+- False abort in local drive mode due to missing bucket check
+- Optional MCP dependency tests now skip cleanly when the `[mcp]` extra is not installed
+
+---
+
+## [0.1.0] — 2024-03-16
+
+### Added
+
+- **Bidirectional sync** to AWS S3 with three-way diff (local / remote / last-known-good)
+- **Client-side AES-256-GCM encryption** with PBKDF2-HMAC-SHA256 key derivation (600,000 iterations)
+- **Glacier archiving** — `sahara archive`, `sahara restore`, `sahara restore-download`
+- **Background daemon** with file-watching via watchdog
+- **Rename detection** — moves are tracked as copy + delete rather than delete + upload
+- **Conflict resolution** — backup, local, remote, and ask strategies
+- **Cost reporting** — `sahara usage` shows storage usage and estimated monthly S3 cost
+- **`.saharaignore`** — gitignore-style rules for excluding files from sync
+- **Multipart uploads** — automatic for files above a configurable threshold
+- **`sahara doctor`** — connectivity and configuration diagnostics
+- `sahara init` interactive setup wizard
+- `sahara config show/get/set` configuration management
+- `sahara history` sync operation log
+- `sahara conflicts` and `sahara resolve`

sahara_memory-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity,
+rights, and contributions of all individuals, regardless of characteristics including
+race, ethnicity, caste, color, age, physical characteristics, neurodiversity,
+disability, sex or gender, gender identity or expression, sexual orientation, language,
+philosophy or religion, national or social origin, socio-economic position, level of
+education, or other status. The same privileges of participation are extended to
+everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's
+expectations for positive behavior. We also understand that our words and actions may
+be interpreted differently than we intend based on culture, background, or native
+language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and
+act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of
+   gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and
+promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary
+   personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed
+   at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or behavior
+   on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered
+   inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality.** Sharing or acting on someone's personal or private
+   information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward
+   any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to
+   be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you
+   contribute.
+3. **Promotional materials.** Sharing marketing or other commercial content in a way
+   that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which
+   includes, links, or describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to
+collaborate. Not every conflict represents a code of conduct violation, and this Code
+of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and
+minimize harm.
+
+Report possible violations privately through the repository's
+[private reporting channel](https://github.com/nidheesh-p/sahara/security/advisories/new).
+Start the report title with `[Conduct]` and include relevant links, context, and any
+supporting records. Do not report conduct incidents in a public issue.
+
+The maintainer will take reports seriously and make every effort to respond promptly.
+Reports will be investigated by reviewing available messages, logs, and other relevant
+records. Investigation and enforcement actions will prioritize safety and
+confidentiality.
+
+## Addressing and Repairing Harm
+
+If an investigation finds that this Code of Conduct has been violated, the following
+enforcement ladder may be used. Depending on the severity of a violation, lower steps
+may be skipped.
+
+1. **Warning**
+   - Event: A violation involving a single incident or series of incidents.
+   - Consequence: A private, written warning from the maintainer.
+   - Repair: A private apology, acknowledgement of responsibility, or clarification of
+     expectations may be requested.
+2. **Temporarily Limited Activities**
+   - Event: A repeated violation after a warning, or the first occurrence of a more
+     serious violation.
+   - Consequence: A private warning with a time-limited cooldown period or restricted
+     participation.
+   - Repair: The person may be asked to reflect, apologize, and re-enter community
+     spaces thoughtfully.
+3. **Temporary Suspension**
+   - Event: A pattern of repeated violations or a single serious violation.
+   - Consequence: Temporary removal from community spaces with conditions for return.
+   - Repair: The person must respect the suspension and meet the stated conditions
+     before returning.
+4. **Permanent Ban**
+   - Event: Repeated violations that other steps have not resolved, or a violation so
+     serious that continued participation would endanger the community.
+   - Consequence: Permanent removal from community spaces and communication channels.
+   - Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is a guideline. The maintainer may use discretion and judgment
+in the best interests of the community.
+
+## Scope
+
+This Code of Conduct applies within all project community spaces and when an individual
+is officially representing the project in public or other spaces. Examples include
+posting through an official account or acting as an appointed representative at an
+online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant, version 3.0](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed
+under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).