synapse-vault 0.1.0__tar.gz

synapse_vault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anshu Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synapse_vault-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: synapse-vault
+Version: 0.1.0
+Summary: A local-first personal knowledge wiki backed by Markdown and SQLite
+Author: Anshu Yadav
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/anshulyadav1976/synapse
+Project-URL: Documentation, https://github.com/anshulyadav1976/synapse#readme
+Project-URL: Issues, https://github.com/anshulyadav1976/synapse/issues
+Keywords: knowledge-graph,local-first,markdown,mcp,personal-knowledge
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Synapse
+
+![Synapse turns scattered history into a linked local knowledge graph](https://raw.githubusercontent.com/anshulyadav1976/synapse/main/docs/demo.gif)
+
+**Point it at text. Get a searchable archive for free. Spend a few cents turning it into a Markdown wiki your agent can query.**
+
+[![CI](https://github.com/anshulyadav1976/synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/anshulyadav1976/synapse/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/synapse-vault)](https://pypi.org/project/synapse-vault/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3157a4)](https://www.python.org/)
+[![zero runtime dependencies](https://img.shields.io/badge/runtime_dependencies-0-13a36f)](https://github.com/anshulyadav1976/synapse/blob/main/pyproject.toml)
+[![MIT](https://img.shields.io/badge/license-MIT-6f5bd3)](https://github.com/anshulyadav1976/synapse/blob/main/LICENSE)
+
+</div>
+
+Give Codex a private, local memory without filling every prompt with your history:
+
+```bash
+codex mcp add synapse -- uvx --from synapse-vault synapse mcp --vault /absolute/path/to/my-brain
+```
+
+Nothing from the vault is injected into the agent's prompt. The agent searches first, then reads one relevant Markdown page. A thousand unopened pages cost zero tokens.
+
+## See it in ten seconds
+
+```bash
+uvx --from synapse-vault synapse serve --demo
+```
+
+That opens a populated 20-page graph. It needs no API key, import, database server, or JavaScript build.
+
+## Keep your own history
+
+```bash
+uvx --from synapse-vault synapse init ./my-brain
+uvx --from synapse-vault synapse ingest ~/Downloads/chatgpt-export --vault ./my-brain
+uvx --from synapse-vault synapse serve --vault ./my-brain
+```
+
+Ingest is local and free: it writes Markdown and builds a disposable SQLite FTS5 index. Search works immediately:
+
+```bash
+uvx --from synapse-vault synapse search "the phrase I remember" --vault ./my-brain
+```
+
+To turn raw history into a linked wiki, estimate first and then build a small resumable batch:
+
+```bash
+export SYNAPSE_API_KEY="..."
+uvx --from synapse-vault synapse build --vault ./my-brain --limit 20 --dry-run
+uvx --from synapse-vault synapse build --vault ./my-brain --limit 20
+```
+
+The build pass is optional. It is a plain `for` loop making one OpenAI-compatible chat-completions request per item. Run it against OpenAI or a local Ollama/LM Studio server; stop and resume without paying twice.
+
+## Markdown is the database
+
+```text
+my-brain/
+├── raw/<source>/<YYYY-MM>/<id>.md   immutable imported history
+├── wiki/<slug>.md                   linked, editable knowledge pages
+├── synapse.db                       disposable FTS5 + graph index
+└── synapse.toml                     model and owner settings
+```
+
+Delete `synapse.db` and `synapse reindex --vault ./my-brain` recreates it. The durable data is ordinary Markdown that works with git, Obsidian, `grep`, and any editor.
+
+## How it works
+
+1. An adapter streams each source into a tiny `Item` shape with stable IDs and timestamps.
+2. Ingest writes immutable raw Markdown and indexes it with SQLite FTS5—no model call.
+3. Build compresses one item and asks any OpenAI-compatible model for complete wiki pages.
+4. `[[wikilinks]]` become edges; a recursive SQLite CTE handles multi-hop traversal.
+5. The one-file dashboard, CLI, Python API, REST API, and MCP server all use the same vault.
+
+## Model providers
+
+Synapse uses one standard-library HTTP POST to `/chat/completions`; there is no provider SDK.
+
+| Provider | Base URL | Status |
+|---|---|---|
+| OpenAI | `https://api.openai.com/v1` | Tested with `gpt-4o-mini` |
+| Ollama | `http://localhost:11434/v1` | Compatible; not yet in CI |
+| LM Studio | `http://localhost:1234/v1` | Compatible; not yet in CI |
+| OpenRouter | `https://openrouter.ai/api/v1` | Compatible; community verification wanted |
+| Groq | `https://api.groq.com/openai/v1` | Compatible; community verification wanted |
+| Together | `https://api.together.xyz/v1` | Compatible; community verification wanted |
+| DeepSeek | `https://api.deepseek.com/v1` | Compatible; community verification wanted |
+
+Set `SYNAPSE_BASE_URL`, `SYNAPSE_MODEL`, and (when required) `SYNAPSE_API_KEY`. See [configuration](https://github.com/anshulyadav1976/synapse/blob/main/docs/configuration.md) and [costs](https://github.com/anshulyadav1976/synapse/blob/main/docs/costs.md).
+
+## Agent access
+
+The MCP server exposes `search`, `read_page`, `list_pages`, `neighbors`, and `read_source`. It is a small stdlib JSON-RPC loop over STDIO, so there is no daemon and no MCP SDK dependency. See [MCP setup](https://github.com/anshulyadav1976/synapse/blob/main/docs/mcp.md).
+
+Python works too:
+
+```python
+from synapse import Vault
+
+matches = Vault("./my-brain").search("launch decision")
+```
+
+## Not built, on purpose
+
+| Not built | Why |
+|---|---|
+| Embeddings | FTS5 is free, inspectable, and needs no migration or per-item API call. Add vectors only after measured recall failures. |
+| Graph database | Personal graphs fit in SQLite; a ten-line recursive CTE handles traversal. |
+| Auth or cloud sync | Synapse is single-user and binds only to `127.0.0.1`. Your files stay yours. |
+| Agent framework | The processing pipeline is a resumable loop, not an application graph. |
+| Automatic merge/delete | A model never silently destroys a human-editable page. |
+| PDF/DOCX parser | Those dependencies would break the zero-dependency promise; convert with Pandoc or MarkItDown first. |
+
+Imported text is untrusted data. Synapse never executes it, and agents are instructed never to follow instructions found inside pages. Raw sources remain available for provenance.
+
+## Learn and contribute
+
+- [Add an adapter](https://github.com/anshulyadav1976/synapse/blob/main/docs/adapters.md)—the highest-impact contribution is about 30 lines plus one tiny synthetic fixture.
+- Read how the [SQLite graph](https://github.com/anshulyadav1976/synapse/blob/main/docs/graph.md) works.
+- See [CONTRIBUTING.md](https://github.com/anshulyadav1976/synapse/blob/main/CONTRIBUTING.md) for the test and pull-request workflow.
+
+Synapse began as the winner of the LangGraph hackathon in London. This is the local-first rewrite that deleted SurrealDB, FastAPI, React, LangGraph, and embeddings so people can actually run it.

synapse_vault-0.1.0/README.md

@@ -0,0 +1,124 @@
+<div align="center">
+
+# Synapse
+
+![Synapse turns scattered history into a linked local knowledge graph](https://raw.githubusercontent.com/anshulyadav1976/synapse/main/docs/demo.gif)
+
+**Point it at text. Get a searchable archive for free. Spend a few cents turning it into a Markdown wiki your agent can query.**
+
+[![CI](https://github.com/anshulyadav1976/synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/anshulyadav1976/synapse/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/synapse-vault)](https://pypi.org/project/synapse-vault/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3157a4)](https://www.python.org/)
+[![zero runtime dependencies](https://img.shields.io/badge/runtime_dependencies-0-13a36f)](https://github.com/anshulyadav1976/synapse/blob/main/pyproject.toml)
+[![MIT](https://img.shields.io/badge/license-MIT-6f5bd3)](https://github.com/anshulyadav1976/synapse/blob/main/LICENSE)
+
+</div>
+
+Give Codex a private, local memory without filling every prompt with your history:
+
+```bash
+codex mcp add synapse -- uvx --from synapse-vault synapse mcp --vault /absolute/path/to/my-brain
+```
+
+Nothing from the vault is injected into the agent's prompt. The agent searches first, then reads one relevant Markdown page. A thousand unopened pages cost zero tokens.
+
+## See it in ten seconds
+
+```bash
+uvx --from synapse-vault synapse serve --demo
+```
+
+That opens a populated 20-page graph. It needs no API key, import, database server, or JavaScript build.
+
+## Keep your own history
+
+```bash
+uvx --from synapse-vault synapse init ./my-brain
+uvx --from synapse-vault synapse ingest ~/Downloads/chatgpt-export --vault ./my-brain
+uvx --from synapse-vault synapse serve --vault ./my-brain
+```
+
+Ingest is local and free: it writes Markdown and builds a disposable SQLite FTS5 index. Search works immediately:
+
+```bash
+uvx --from synapse-vault synapse search "the phrase I remember" --vault ./my-brain
+```
+
+To turn raw history into a linked wiki, estimate first and then build a small resumable batch:
+
+```bash
+export SYNAPSE_API_KEY="..."
+uvx --from synapse-vault synapse build --vault ./my-brain --limit 20 --dry-run
+uvx --from synapse-vault synapse build --vault ./my-brain --limit 20
+```
+
+The build pass is optional. It is a plain `for` loop making one OpenAI-compatible chat-completions request per item. Run it against OpenAI or a local Ollama/LM Studio server; stop and resume without paying twice.
+
+## Markdown is the database
+
+```text
+my-brain/
+├── raw/<source>/<YYYY-MM>/<id>.md   immutable imported history
+├── wiki/<slug>.md                   linked, editable knowledge pages
+├── synapse.db                       disposable FTS5 + graph index
+└── synapse.toml                     model and owner settings
+```
+
+Delete `synapse.db` and `synapse reindex --vault ./my-brain` recreates it. The durable data is ordinary Markdown that works with git, Obsidian, `grep`, and any editor.
+
+## How it works
+
+1. An adapter streams each source into a tiny `Item` shape with stable IDs and timestamps.
+2. Ingest writes immutable raw Markdown and indexes it with SQLite FTS5—no model call.
+3. Build compresses one item and asks any OpenAI-compatible model for complete wiki pages.
+4. `[[wikilinks]]` become edges; a recursive SQLite CTE handles multi-hop traversal.
+5. The one-file dashboard, CLI, Python API, REST API, and MCP server all use the same vault.
+
+## Model providers
+
+Synapse uses one standard-library HTTP POST to `/chat/completions`; there is no provider SDK.
+
+| Provider | Base URL | Status |
+|---|---|---|
+| OpenAI | `https://api.openai.com/v1` | Tested with `gpt-4o-mini` |
+| Ollama | `http://localhost:11434/v1` | Compatible; not yet in CI |
+| LM Studio | `http://localhost:1234/v1` | Compatible; not yet in CI |
+| OpenRouter | `https://openrouter.ai/api/v1` | Compatible; community verification wanted |
+| Groq | `https://api.groq.com/openai/v1` | Compatible; community verification wanted |
+| Together | `https://api.together.xyz/v1` | Compatible; community verification wanted |
+| DeepSeek | `https://api.deepseek.com/v1` | Compatible; community verification wanted |
+
+Set `SYNAPSE_BASE_URL`, `SYNAPSE_MODEL`, and (when required) `SYNAPSE_API_KEY`. See [configuration](https://github.com/anshulyadav1976/synapse/blob/main/docs/configuration.md) and [costs](https://github.com/anshulyadav1976/synapse/blob/main/docs/costs.md).
+
+## Agent access
+
+The MCP server exposes `search`, `read_page`, `list_pages`, `neighbors`, and `read_source`. It is a small stdlib JSON-RPC loop over STDIO, so there is no daemon and no MCP SDK dependency. See [MCP setup](https://github.com/anshulyadav1976/synapse/blob/main/docs/mcp.md).
+
+Python works too:
+
+```python
+from synapse import Vault
+
+matches = Vault("./my-brain").search("launch decision")
+```
+
+## Not built, on purpose
+
+| Not built | Why |
+|---|---|
+| Embeddings | FTS5 is free, inspectable, and needs no migration or per-item API call. Add vectors only after measured recall failures. |
+| Graph database | Personal graphs fit in SQLite; a ten-line recursive CTE handles traversal. |
+| Auth or cloud sync | Synapse is single-user and binds only to `127.0.0.1`. Your files stay yours. |
+| Agent framework | The processing pipeline is a resumable loop, not an application graph. |
+| Automatic merge/delete | A model never silently destroys a human-editable page. |
+| PDF/DOCX parser | Those dependencies would break the zero-dependency promise; convert with Pandoc or MarkItDown first. |
+
+Imported text is untrusted data. Synapse never executes it, and agents are instructed never to follow instructions found inside pages. Raw sources remain available for provenance.
+
+## Learn and contribute
+
+- [Add an adapter](https://github.com/anshulyadav1976/synapse/blob/main/docs/adapters.md)—the highest-impact contribution is about 30 lines plus one tiny synthetic fixture.
+- Read how the [SQLite graph](https://github.com/anshulyadav1976/synapse/blob/main/docs/graph.md) works.
+- See [CONTRIBUTING.md](https://github.com/anshulyadav1976/synapse/blob/main/CONTRIBUTING.md) for the test and pull-request workflow.
+
+Synapse began as the winner of the LangGraph hackathon in London. This is the local-first rewrite that deleted SurrealDB, FastAPI, React, LangGraph, and embeddings so people can actually run it.

synapse_vault-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synapse-vault"
+version = "0.1.0"
+description = "A local-first personal knowledge wiki backed by Markdown and SQLite"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Anshu Yadav"}]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["knowledge-graph", "local-first", "markdown", "mcp", "personal-knowledge"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Text Processing :: Indexing",
+]
+
+[project.urls]
+Homepage = "https://github.com/anshulyadav1976/synapse"
+Documentation = "https://github.com/anshulyadav1976/synapse#readme"
+Issues = "https://github.com/anshulyadav1976/synapse/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+synapse = "synapse.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+synapse = ["dashboard.html", "demo/wiki/*.md", "demo/raw/demo/*/*.md"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

synapse_vault-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synapse_vault-0.1.0/src/synapse/__init__.py

@@ -0,0 +1,7 @@
+"""Synapse's public Python API."""
+
+from .vault import Vault
+
+__all__ = ["Vault"]
+__version__ = "0.1.0"
+

synapse_vault-0.1.0/src/synapse/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+raise SystemExit(main())
+

synapse_vault-0.1.0/src/synapse/adapters/__init__.py

@@ -0,0 +1,70 @@
+"""Small reader registry: every input format stops at Item."""
+
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import TypeAlias
+from zipfile import BadZipFile, ZipFile
+
+from ..models import Item
+
+Reader: TypeAlias = Callable[[Path], Iterator[Item]]
+READERS: dict[str, Reader] = {}
+
+
+def adapter(name: str) -> Callable[[Reader], Reader]:
+    def register(reader: Reader) -> Reader:
+        READERS[name] = reader
+        return reader
+
+    return register
+
+
+def _zip_names(path: Path) -> list[str]:
+    try:
+        with ZipFile(path) as archive:
+            return archive.namelist()
+    except (BadZipFile, OSError):
+        return []
+
+
+def detect(path: Path) -> str:
+    if path.is_dir():
+        names = {child.name for child in path.iterdir()}
+        if "export_manifest.json" in names or any(
+            name.startswith("conversations-") and name.endswith(".json") for name in names
+        ):
+            return "chatgpt"
+        return "dir"
+    if path.name == "conversations.json" or (
+        path.name.startswith("conversations-") and path.suffix == ".json"
+    ):
+        return "chatgpt"
+    if path.name == "chat.html":
+        return "chatgpt"
+    if path.suffix.lower() == ".zip":
+        names = _zip_names(path)
+        if any(
+            Path(name).name == "export_manifest.json"
+            or Path(name).name == "conversations.json"
+            or Path(name).name == "chat.html"
+            or (Path(name).name.startswith("conversations-") and name.endswith(".json"))
+            for name in names
+        ):
+            return "chatgpt"
+    return "file"
+
+
+def read(path: str | Path, format_name: str | None = None) -> Iterator[Item]:
+    source = Path(path).expanduser().resolve()
+    name = format_name or detect(source)
+    try:
+        reader = READERS[name]
+    except KeyError as error:
+        choices = ", ".join(sorted(READERS))
+        raise ValueError(f"Unknown format {name!r}. Available formats: {choices}") from error
+    yield from reader(source)
+
+
+# Importing registers the built-in readers while keeping contributor adapters tiny.
+from . import chatgpt, files  # noqa: F401
+

synapse_vault-0.1.0/src/synapse/adapters/chatgpt.py

@@ -0,0 +1,152 @@
+"""Reader for modern and legacy ChatGPT exports."""
+
+import json
+import mmap
+import re
+from collections.abc import Iterable, Iterator
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
+from typing import Any
+from zipfile import ZipFile
+
+from ..models import Item, Turn
+from . import adapter
+
+SHARD = re.compile(r"conversations-\d+\.json$")
+
+
+def _iso(value: object) -> str:
+    try:
+        return datetime.fromtimestamp(float(value), UTC).isoformat()
+    except (TypeError, ValueError, OSError):
+        return datetime.fromtimestamp(0, UTC).isoformat()
+
+
+def _parts(content: dict[str, Any]) -> str:
+    return "\n".join(part for part in content.get("parts", []) if isinstance(part, str)).strip()
+
+
+def _conversation(data: dict[str, Any]) -> Item:
+    messages: list[tuple[float, int, Turn]] = []
+    for order, node in enumerate(data.get("mapping", {}).values()):
+        message = node.get("message") or {}
+        text = _parts(message.get("content") or {})
+        if not text:
+            continue
+        author = message.get("author") or {}
+        role = str(author.get("role") or "unknown")
+        speaker = "me" if role == "user" else str(author.get("name") or role)
+        created = message.get("create_time")
+        messages.append((float(created or 0), order, Turn(speaker, text, _iso(created))))
+    messages.sort(key=lambda entry: (entry[0], entry[1]))
+    identifier = str(data.get("conversation_id") or data.get("id") or "")
+    if not identifier:
+        raise ValueError("A ChatGPT conversation is missing both conversation_id and id")
+    return Item(
+        id=identifier,
+        source="chatgpt",
+        title=str(data.get("title") or "Untitled conversation"),
+        ts=_iso(data.get("create_time")),
+        turns=[entry[2] for entry in messages],
+    )
+
+
+def _items(conversations: Iterable[dict[str, Any]]) -> Iterator[Item]:
+    for conversation in conversations:
+        yield _conversation(conversation)
+
+
+def _manifest_files(data: dict[str, Any]) -> list[str]:
+    return [
+        str(entry["path"])
+        for entry in data.get("export_files", [])
+        if isinstance(entry, dict)
+        and "path" in entry
+        and (SHARD.search(str(entry["path"])) or PurePosixPath(str(entry["path"])).name == "conversations.json")
+    ]
+
+
+def _folder_files(path: Path) -> list[Path]:
+    manifest = path / "export_manifest.json"
+    if manifest.exists():
+        names = _manifest_files(json.loads(manifest.read_text(encoding="utf-8")))
+        found = [path / name for name in names if (path / name).is_file()]
+        if found:
+            return found
+    shards = sorted(path.glob("conversations-*.json"))
+    if shards:
+        return shards
+    legacy = path / "conversations.json"
+    return [legacy] if legacy.exists() else []
+
+
+def _from_html_bytes(data: bytes, label: str) -> Iterator[Item]:
+    marker = b"var jsonData ="
+    start = data.find(marker)
+    if start < 0:
+        raise ValueError(f"No 'var jsonData =' conversation payload found in {label}")
+    start += len(marker)
+    end = data.find(b";</script>", start)
+    if end < 0:
+        end = data.find(b";\n", start)
+    if end < 0:
+        raise ValueError(f"The ChatGPT payload in {label} has no closing semicolon")
+    yield from _items(json.loads(data[start:end]))
+
+
+def _from_html(path: Path) -> Iterator[Item]:
+    with path.open("rb") as handle, mmap.mmap(handle.fileno(), 0, access=mmap.ACCESS_READ) as data:
+        yield from _from_html_bytes(data, str(path))
+
+
+def _from_zip(path: Path) -> Iterator[Item]:
+    with ZipFile(path) as archive:
+        names = archive.namelist()
+        manifest_name = next((name for name in names if PurePosixPath(name).name == "export_manifest.json"), None)
+        selected: list[str] = []
+        if manifest_name:
+            manifest = json.loads(archive.read(manifest_name))
+            base = PurePosixPath(manifest_name).parent
+            available = set(names)
+            selected = [str(base / name) for name in _manifest_files(manifest) if str(base / name) in available]
+        if not selected:
+            selected = sorted(
+                name
+                for name in names
+                if SHARD.search(PurePosixPath(name).name)
+                or PurePosixPath(name).name == "conversations.json"
+            )
+        if selected:
+            for name in selected:
+                yield from _items(json.loads(archive.read(name)))
+            return
+        html = next((name for name in names if PurePosixPath(name).name == "chat.html"), None)
+        if html:
+            yield from _from_html_bytes(archive.read(html), f"{path}!{html}")
+            return
+    raise ValueError(f"No ChatGPT conversations found in {path}")
+
+
+@adapter("chatgpt")
+def read_chatgpt(path: Path) -> Iterator[Item]:
+    if path.is_dir():
+        files = _folder_files(path)
+        if not files:
+            html = path / "chat.html"
+            if html.exists():
+                yield from _from_html(html)
+                return
+            raise ValueError(
+                f"No conversations found in {path}. Modern exports shard them as "
+                "conversations-000.json; pass --format chatgpt to force detection."
+            )
+        for file in files:
+            yield from _items(json.loads(file.read_text(encoding="utf-8")))
+        return
+    if path.suffix.lower() == ".zip":
+        yield from _from_zip(path)
+    elif path.name == "chat.html":
+        yield from _from_html(path)
+    else:
+        yield from _items(json.loads(path.read_text(encoding="utf-8")))
+