customchat-app 0.1.0__tar.gz

customchat_app-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harsh Kashyap
+
+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.

customchat_app-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: customchat-app
+Version: 0.1.0
+Summary: Build a chat application over any evidence source from one YAML file.
+License: MIT
+Project-URL: Repository, https://github.com/Harsh23Kashyap/customchat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.3
+Provides-Extra: documents
+Requires-Dist: pypdf>=4; extra == "documents"
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=3; extra == "semantic"
+Dynamic: license-file
+
+# CustomChat
+
+[![Installer tests](https://github.com/Harsh23Kashyap/customchat/actions/workflows/installer.yml/badge.svg)](https://github.com/Harsh23Kashyap/customchat/actions/workflows/installer.yml)
+
+A chat app over your documents, configured with one YAML file. Answers cite their sources. Includes offline Demo, saved chats, themes and a local configuration page.
+
+## Start on a fresh computer
+
+Open **Terminal** on macOS/Linux, or **PowerShell** on Windows. Copy the command for your computer. You do not need to install Python, Git, uv or uvx first.
+
+**macOS / Linux** (needs curl, included on macOS and many Linux systems):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Harsh23Kashyap/customchat/main/start.sh | sh
+```
+
+**Windows PowerShell**:
+
+```powershell
+& { $f = Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName() + '.ps1'); try { Invoke-WebRequest https://raw.githubusercontent.com/Harsh23Kashyap/customchat/main/start.ps1 -OutFile $f; & powershell -NoProfile -ExecutionPolicy Bypass -File $f } finally { Remove-Item $f -ErrorAction SilentlyContinue } }
+```
+
+These scripts detect uv or download it from its official installer, obtain Python 3.12 if needed, then run CustomChat with `uv tool run` (the same operation as `uvx`). No administrator access is needed. First setup needs internet and writable disk space. Review [start.sh](start.sh) or [start.ps1](start.ps1) before running downloaded software. Network restrictions or a locked-down work computer can still prevent setup; the terminal shows the error.
+
+The app opens in your browser. If that does not happen, open the printed localhost URL. Starts with offline Demo: no API key, account, paid AI calls or cloud hosting. Press **Ctrl+C** to stop. Run the same command from the same folder to return to your chats. Your workspace is `customchat-app` in that folder, separate from the software environment. Existing app files are not overwritten.
+
+### Already have uv?
+
+```sh
+uvx --python 3.12 --from https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip customchat start
+```
+
+This archive route needs no Git. It installs from current `main`, which can change. PyPI publication of `customchat-app` is pending; do not use `uvx customchat` or `pip install customchat`, which target another project.
+
+### Will it conflict with my other Python packages?
+
+`uvx` runs CustomChat and its dependencies in a **separate tool environment**. It does not install packages into your system Python or another project's virtual environment. You do not need to create a venv for the commands above. The bootstrap also removes inherited `PYTHONPATH`/`PYTHONHOME` overrides for this run. Your documents and chats live outside uv's cache.
+
+Isolation avoids shared dependency-version conflicts, not every possible computer problem. First install still needs internet; disk permissions, antivirus, proxies and platform support can affect setup. If the usual port is busy, CustomChat chooses another and prints its URL.
+
+### Prefer pip? Use a separate venv
+
+With **Python 3.10+** already installed, open a new empty folder and run:
+
+```sh
+# macOS / Linux
+python3 -m venv .venv
+.venv/bin/python -m pip install https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip
+.venv/bin/python -m customchat start
+```
+
+```powershell
+# Windows
+py -3 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip
+.\.venv\Scripts\python.exe -m customchat start
+```
+
+These commands use the venv directly; no activation or PowerShell activation-policy change is needed. Avoid global `pip install` for this app. To check dependencies, run the venv's Python with `-m pip check`. Use a new folder or a new venv name rather than overwriting an environment you already use.
+
+## Configure your own app
+
+Choose an AI provider in Configuration or your app YAML. Keep keys in environment variables/private local storage, never YAML or Git.
+
+```sh
+uvx --python 3.12 --from https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip customchat start --directory my-chat
+```
+
+Edit `my-chat/app.yaml` and add documents in the app folder. [Configuration reference](docs/DESIGN.md).
+
+For a chat-only interface, append `--lock-config` or set `CUSTOMCHAT_CONFIG=off`. Configuration pages and settings/key/model endpoints then return 404. Remove the lock on restart to configure again.
+
+## More
+
+- [Install choices, clone installers and validation](docs/INSTALL.md)
+- [Hosting and deployment](docs/DEPLOY_OPTIONS.md) (no public deployment tested here)
+- [Architecture](docs/DESIGN.md)
+- Tests: `python -m unittest discover -s tests`
+
+CustomChat is the conversation counterpart of [Custom-Nerd](https://github.com/Harsh23Kashyap/Custom-Nerd). DietChat and WirelessChat are included example apps.
+
+## Authors and license
+
+Harsh Kashyap, Shela Wu. Advisor: Dennis Shasha. MIT license. See [LICENSE](LICENSE).

customchat_app-0.1.0/README.md

@@ -0,0 +1,84 @@
+# CustomChat
+
+[![Installer tests](https://github.com/Harsh23Kashyap/customchat/actions/workflows/installer.yml/badge.svg)](https://github.com/Harsh23Kashyap/customchat/actions/workflows/installer.yml)
+
+A chat app over your documents, configured with one YAML file. Answers cite their sources. Includes offline Demo, saved chats, themes and a local configuration page.
+
+## Start on a fresh computer
+
+Open **Terminal** on macOS/Linux, or **PowerShell** on Windows. Copy the command for your computer. You do not need to install Python, Git, uv or uvx first.
+
+**macOS / Linux** (needs curl, included on macOS and many Linux systems):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Harsh23Kashyap/customchat/main/start.sh | sh
+```
+
+**Windows PowerShell**:
+
+```powershell
+& { $f = Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName() + '.ps1'); try { Invoke-WebRequest https://raw.githubusercontent.com/Harsh23Kashyap/customchat/main/start.ps1 -OutFile $f; & powershell -NoProfile -ExecutionPolicy Bypass -File $f } finally { Remove-Item $f -ErrorAction SilentlyContinue } }
+```
+
+These scripts detect uv or download it from its official installer, obtain Python 3.12 if needed, then run CustomChat with `uv tool run` (the same operation as `uvx`). No administrator access is needed. First setup needs internet and writable disk space. Review [start.sh](start.sh) or [start.ps1](start.ps1) before running downloaded software. Network restrictions or a locked-down work computer can still prevent setup; the terminal shows the error.
+
+The app opens in your browser. If that does not happen, open the printed localhost URL. Starts with offline Demo: no API key, account, paid AI calls or cloud hosting. Press **Ctrl+C** to stop. Run the same command from the same folder to return to your chats. Your workspace is `customchat-app` in that folder, separate from the software environment. Existing app files are not overwritten.
+
+### Already have uv?
+
+```sh
+uvx --python 3.12 --from https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip customchat start
+```
+
+This archive route needs no Git. It installs from current `main`, which can change. PyPI publication of `customchat-app` is pending; do not use `uvx customchat` or `pip install customchat`, which target another project.
+
+### Will it conflict with my other Python packages?
+
+`uvx` runs CustomChat and its dependencies in a **separate tool environment**. It does not install packages into your system Python or another project's virtual environment. You do not need to create a venv for the commands above. The bootstrap also removes inherited `PYTHONPATH`/`PYTHONHOME` overrides for this run. Your documents and chats live outside uv's cache.
+
+Isolation avoids shared dependency-version conflicts, not every possible computer problem. First install still needs internet; disk permissions, antivirus, proxies and platform support can affect setup. If the usual port is busy, CustomChat chooses another and prints its URL.
+
+### Prefer pip? Use a separate venv
+
+With **Python 3.10+** already installed, open a new empty folder and run:
+
+```sh
+# macOS / Linux
+python3 -m venv .venv
+.venv/bin/python -m pip install https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip
+.venv/bin/python -m customchat start
+```
+
+```powershell
+# Windows
+py -3 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip
+.\.venv\Scripts\python.exe -m customchat start
+```
+
+These commands use the venv directly; no activation or PowerShell activation-policy change is needed. Avoid global `pip install` for this app. To check dependencies, run the venv's Python with `-m pip check`. Use a new folder or a new venv name rather than overwriting an environment you already use.
+
+## Configure your own app
+
+Choose an AI provider in Configuration or your app YAML. Keep keys in environment variables/private local storage, never YAML or Git.
+
+```sh
+uvx --python 3.12 --from https://github.com/Harsh23Kashyap/customchat/archive/refs/heads/main.zip customchat start --directory my-chat
+```
+
+Edit `my-chat/app.yaml` and add documents in the app folder. [Configuration reference](docs/DESIGN.md).
+
+For a chat-only interface, append `--lock-config` or set `CUSTOMCHAT_CONFIG=off`. Configuration pages and settings/key/model endpoints then return 404. Remove the lock on restart to configure again.
+
+## More
+
+- [Install choices, clone installers and validation](docs/INSTALL.md)
+- [Hosting and deployment](docs/DEPLOY_OPTIONS.md) (no public deployment tested here)
+- [Architecture](docs/DESIGN.md)
+- Tests: `python -m unittest discover -s tests`
+
+CustomChat is the conversation counterpart of [Custom-Nerd](https://github.com/Harsh23Kashyap/Custom-Nerd). DietChat and WirelessChat are included example apps.
+
+## Authors and license
+
+Harsh Kashyap, Shela Wu. Advisor: Dennis Shasha. MIT license. See [LICENSE](LICENSE).

customchat_app-0.1.0/customchat/__init__.py

@@ -0,0 +1,2 @@
+"""CustomChat: build a chat application over any evidence source from one YAML file."""
+__version__ = "0.1.0"

customchat_app-0.1.0/customchat/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

customchat_app-0.1.0/customchat/accounts.py

@@ -0,0 +1,95 @@
+"""Accounts: sign up, sign in, sign out, change password. Standard library only.
+Passwords are stored as salted PBKDF2 hashes. Sessions are random tokens kept only as hashes."""
+import hashlib, hmac, os, re, secrets, time
+
+ITER = 200_000
+SESSION_DAYS = 30
+EMAIL = re.compile(r"^[^@\s]{1,64}@[^@\s]{1,190}\.[^@\s]{2,}$")
+
+TABLES = """
+CREATE TABLE IF NOT EXISTS users(id TEXT PRIMARY KEY, email TEXT UNIQUE, name TEXT, salt BLOB, hash BLOB, created REAL);
+CREATE TABLE IF NOT EXISTS sessions(token_hash TEXT PRIMARY KEY, user TEXT, expires REAL);
+CREATE TABLE IF NOT EXISTS attempts(key TEXT, ts REAL);
+"""
+
+
+def _hash(pw, salt):
+    return hashlib.pbkdf2_hmac("sha256", pw.encode(), salt, ITER)
+
+
+def _th(token):
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+class Accounts:
+    def __init__(self, store, allow_signup=True):
+        self.s = store
+        self.allow_signup = allow_signup
+        with store.c() as c:
+            c.executescript(TABLES)
+
+    def _check_pw(self, pw):
+        if not isinstance(pw, str) or not 8 <= len(pw) <= 200:
+            raise ValueError("Password must be 8 to 200 characters")
+
+    def signup(self, email, name, pw):
+        if not self.allow_signup and self.s.q("SELECT 1 FROM users LIMIT 1"):
+            raise PermissionError("Sign-ups are closed")
+        email = str(email or "").strip().lower()
+        if not EMAIL.match(email):
+            raise ValueError("Enter a valid email address")
+        self._check_pw(pw)
+        if self.s.q("SELECT 1 FROM users WHERE email=?", (email,), one=True):
+            raise ValueError("An account with that email already exists")
+        uid, salt = "u_" + secrets.token_hex(8), os.urandom(16)
+        self.s.q("INSERT INTO users VALUES(?,?,?,?,?,?)", (uid, email, str(name or "").strip()[:60] or email.split("@")[0], salt, _hash(pw, salt), time.time()), write=True)
+        return uid
+
+    def _throttle(self, key):
+        now = time.time()
+        self.s.q("DELETE FROM attempts WHERE ts<?", (now - 600,), write=True)
+        if len(self.s.q("SELECT 1 FROM attempts WHERE key=?", (key,))) >= 8:
+            raise PermissionError("Too many attempts, try again in a few minutes")
+
+    def login(self, email, pw, ip=""):
+        email = str(email or "").strip().lower()
+        self._throttle(email)
+        u = self.s.q("SELECT * FROM users WHERE email=?", (email,), one=True)
+        ok = bool(u) and hmac.compare_digest(_hash(str(pw or ""), u["salt"]), u["hash"])
+        if not ok:
+            self.s.q("INSERT INTO attempts VALUES(?,?)", (email, time.time()), write=True)
+            raise PermissionError("Wrong email or password")
+        return u["id"], self._session(u["id"])
+
+    def _session(self, uid):
+        t = secrets.token_urlsafe(32)
+        self.s.q("INSERT INTO sessions VALUES(?,?,?)", (_th(t), uid, time.time() + SESSION_DAYS * 86400), write=True)
+        return t
+
+    def user_for(self, token):
+        if not token:
+            return None
+        r = self.s.q("SELECT u.id,u.email,u.name FROM sessions s JOIN users u ON u.id=s.user WHERE s.token_hash=? AND s.expires>?", (_th(token), time.time()), one=True)
+        return dict(r) if r else None
+
+    def logout(self, token):
+        if token:
+            self.s.q("DELETE FROM sessions WHERE token_hash=?", (_th(token),), write=True)
+
+    def change_password(self, uid, old, new, keep_token=None):
+        u = self.s.q("SELECT * FROM users WHERE id=?", (uid,), one=True)
+        if not u or not hmac.compare_digest(_hash(str(old or ""), u["salt"]), u["hash"]):
+            raise PermissionError("Current password is wrong")
+        self._check_pw(new)
+        salt = os.urandom(16)
+        self.s.q("UPDATE users SET salt=?,hash=? WHERE id=?", (salt, _hash(new, salt), uid), write=True)
+        # sign out every other device
+        self.s.q("DELETE FROM sessions WHERE user=? AND token_hash!=?", (uid, _th(keep_token or "")), write=True)
+
+    def delete_account(self, uid, pw):
+        u = self.s.q("SELECT * FROM users WHERE id=?", (uid,), one=True)
+        if not u or not hmac.compare_digest(_hash(str(pw or ""), u["salt"]), u["hash"]):
+            raise PermissionError("Password is wrong")
+        for t, col in (("sessions", "user"), ("chats", "owner"), ("topics", "owner"), ("feedback", "owner"), ("states", "owner"), ("profile", "owner"), ("uploads", "owner")):
+            self.s.q(f"DELETE FROM {t} WHERE {col}=?", (uid,), write=True)
+        self.s.q("DELETE FROM users WHERE id=?", (uid,), write=True)

customchat_app-0.1.0/customchat/actions.py

@@ -0,0 +1,31 @@
+"""Finite, registered actions with owner-bound, expiring, one-use review tickets."""
+import copy,json,secrets,threading,time
+REGISTRY={
+ 'list_notes':{'label':'List my notes','mode':'read','fields':{}},
+ 'save_note':{'label':'Save a private note','mode':'write','fields':{'title':{'type':'string','maxLength':120},'text':{'type':'string','maxLength':4000}}},
+}
+class Actions:
+ def __init__(self,cfg,store):self.cfg,self.store=cfg,store;self.lock=threading.RLock()
+ def catalog(self):
+  policy=self.cfg.get('actions',{});allow=policy.get('allow')
+  return [dict(id=k,**copy.deepcopy(v)) for k,v in REGISTRY.items() if (allow is None or k in allow) and (v['mode']!='write' or policy.get('writes',True))]
+ def prepare(self,owner,tool,args):
+  spec=next((x for x in self.catalog() if x['id']==tool),None)
+  if not spec:raise PermissionError('Action unavailable')
+  if not isinstance(args,dict) or set(args)!=set(spec['fields']):raise ValueError('Use exactly the declared action fields')
+  for k,f in spec['fields'].items():
+   if not isinstance(args[k],str) or not args[k].strip() or len(args[k])>f['maxLength']:raise ValueError(k+' needs nonempty text within '+str(f['maxLength'])+' characters')
+  ticket=secrets.token_urlsafe(24);payload={'tool':tool,'args':copy.deepcopy(args),'expires':time.time()+300,'used':False}
+  self.store.save_state(owner,'action-'+ticket,payload)
+  return dict(ticket=ticket,tool=tool,label=spec['label'],mode=spec['mode'],args=args,expires_in=300)
+ def execute(self,owner,ticket):
+  with self.lock:
+   p=self.store.get_state(owner,'action-'+str(ticket))
+   if p['used'] or time.time()>p['expires']:raise PermissionError('Review expired or already used')
+   if p['tool'] not in {x['id'] for x in self.catalog()}:raise PermissionError('Action no longer allowed')
+   p['used']=True;self.store.save_state(owner,'action-'+str(ticket),p)
+   if p['tool']=='save_note':
+    name='note-'+secrets.token_hex(8);self.store.save_state(owner,name,p['args']);return {'saved':True,'id':name}
+   if p['tool']=='list_notes':
+    return {'notes':[self.store.get_state(owner,n) for n in self.store.states(owner) if n.startswith('note-')][:100]}
+   raise PermissionError('Action unavailable')

customchat_app-0.1.0/customchat/budget.py

@@ -0,0 +1,74 @@
+"""Durable, atomic request/call quotas. Dollar limits fail closed without a meter."""
+import copy, datetime, hashlib, json, math, sqlite3, threading
+from pathlib import Path
+from .providers import ProviderError
+
+DEFAULT = {'daily_questions': 0, 'user_daily_questions': 0, 'daily_model_calls': 0, 'spend_cap_usd': None}
+
+class BudgetError(ProviderError):
+    pass
+
+def clean(raw):
+    if not isinstance(raw, dict): raise ValueError('budget must be a mapping')
+    if set(raw) - set(DEFAULT): raise ValueError('Unknown budget key')
+    out = dict(DEFAULT, **raw)
+    for k in ('daily_questions','user_daily_questions','daily_model_calls'):
+        v=out[k]
+        if isinstance(v,bool) or not isinstance(v,int) or not math.isfinite(v) or not 0 <= v <= 10000000:
+            raise ValueError(k + ' must be a whole number from 0 to 10000000')
+    v=out['spend_cap_usd']
+    if v is not None and (isinstance(v,bool) or not isinstance(v,(int,float)) or not math.isfinite(v) or not 0 <= v <= 1000000):
+        raise ValueError('spend_cap_usd must be null or 0-1000000')
+    return out
+
+class Budget:
+    def __init__(self, cfg, folder=None):
+        self.value=clean(cfg.get('budget',{}));self.folder=Path(folder) if folder else None
+        self.lock=threading.RLock()
+        if self.folder:
+            self.folder.mkdir(parents=True,exist_ok=True)
+            path=self.folder/'budget.json'
+            if path.exists():self.value=clean(json.loads(path.read_text()))
+        self.db=sqlite3.connect(str(self.folder/'budget.db') if self.folder else ':memory:',check_same_thread=False)
+        self.db.execute('CREATE TABLE IF NOT EXISTS usage(day TEXT, scope TEXT, kind TEXT, amount INTEGER, PRIMARY KEY(day,scope,kind))');self.db.commit()
+    def day(self):return datetime.datetime.now(datetime.timezone.utc).date().isoformat()
+    def take(self, kind, owner=''):
+        with self.lock:
+            limits=[('*', self.value['daily_questions' if kind=='question' else 'daily_model_calls'])]
+            if kind=='question':limits.append(('user:' + hashlib.sha256(str(owner).encode()).hexdigest(),self.value['user_daily_questions']))
+            day=self.day()
+            try:
+                self.db.execute('BEGIN IMMEDIATE')
+                for scope,limit in limits:
+                    row=self.db.execute('SELECT amount FROM usage WHERE day=? AND scope=? AND kind=?',(day,scope,kind)).fetchone()
+                    if limit and (row[0] if row else 0)>=limit:raise BudgetError('Daily '+kind+' limit reached. Resets at midnight UTC.',429)
+                for scope,_ in limits:
+                    self.db.execute('INSERT INTO usage VALUES(?,?,?,1) ON CONFLICT(day,scope,kind) DO UPDATE SET amount=amount+1',(day,scope,kind))
+                self.db.commit()
+            except Exception:
+                self.db.rollback();raise
+    def save(self, raw):
+        value=clean(raw)
+        with self.lock:
+            if self.folder:
+                path=self.folder/'budget.json';tmp=self.folder/'budget.json.tmp'
+                tmp.write_text(json.dumps(value,indent=2));tmp.replace(path)
+            self.value=value
+        return self.view()
+    def view(self):
+        with self.lock:
+            rows=self.db.execute('SELECT kind,amount FROM usage WHERE day=? AND scope=?',(self.day(),'*')).fetchall()
+            return {'limits':copy.deepcopy(self.value),'used':dict(rows),'day':self.day(),'reset_timezone':'UTC',
+                    'spend_meter':'unavailable','spend_note':'Dollar caps block all non-Demo model calls. No verified provider billing meter is installed.'}
+    def wrap(self, provider):return Guarded(provider,self)
+
+class Guarded:
+    def __init__(self, provider, budget):self.provider,self.budget=provider,budget
+    def _check(self):
+        from .providers import Mock
+        if self.budget.value['spend_cap_usd'] is not None and not isinstance(self.provider,Mock):
+            raise BudgetError('Dollar cap is set, but verified billing is unavailable. Non-Demo model calls are blocked.',429)
+        self.budget.take('model')
+    def complete(self,messages):self._check();return self.provider.complete(messages)
+    def stream(self,messages):
+        self._check();yield from self.provider.stream(messages)

customchat_app-0.1.0/customchat/cli.py

@@ -0,0 +1,136 @@
+"""customchat init | validate | run | doctor | ask"""
+import argparse, json, os, shutil, sys, urllib.request
+from . import schema, __version__
+
+TEMPLATE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "templates", "minimal")
+
+
+def main(argv=None):
+    try:
+        _main(argv)
+    except schema.ConfigError as e:
+        sys.exit("There is a problem with the app file:\n  %s" % e)
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+
+def _main(argv=None):
+    ap = argparse.ArgumentParser(prog="customchat", description="Build a chat app over any evidence source.")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    i = sub.add_parser("init", help="scaffold a new app folder"); i.add_argument("name")
+    st = sub.add_parser("start", help="create a local Demo workspace if absent, then run it")
+    st.add_argument("--directory", default="customchat-app", help="persistent workspace, never the tool cache")
+    st.add_argument("--port", type=int, default=8080)
+    st.add_argument("--no-browser", action="store_true")
+    st.add_argument("--lock-config", action="store_true")
+    v = sub.add_parser("validate", help="check an app file"); v.add_argument("app")
+    r = sub.add_parser("run", help="serve an app"); r.add_argument("app"); r.add_argument("--host"); r.add_argument("--port", type=int)
+    df = sub.add_parser("config-diff", help="preview changed keys and effects without values"); df.add_argument("app"); df.add_argument("candidate")
+    ca = sub.add_parser("config-apply", help="apply exact previewed config with private rollback backup")
+    ca.add_argument("app"); ca.add_argument("candidate"); ca.add_argument("--current-sha", required=True); ca.add_argument("--candidate-sha", required=True)
+    sub.add_parser("config-schema", help="print JSON Schema for editor autocomplete")
+    cd = sub.add_parser("config-doctor", help="offline line/key configuration checks"); cd.add_argument("app")
+    d = sub.add_parser("doctor", help="check provider and sources"); d.add_argument("app")
+    ev = sub.add_parser("eval", help="run questions from a file and report citation coverage"); ev.add_argument("app"); ev.add_argument("questions", help="text file, one question per line")
+    a = sub.add_parser("ask", help="ask one question from the terminal"); a.add_argument("app"); a.add_argument("question"); a.add_argument("--json", action="store_true")
+    ex = sub.add_parser("export", help="export app YAML, look, prompts and local documents, without private state")
+    ex.add_argument("app"); ex.add_argument("output", help="new ZIP file; never overwritten")
+    if argv is None: argv = sys.argv[1:]
+    if not argv: argv = ["start"]
+    args = ap.parse_args(argv)
+    if args.cmd == "config-diff":
+        from .configchange import diff
+        print(json.dumps(diff(args.app,args.candidate),indent=2)); return
+    if args.cmd == "config-apply":
+        from .configchange import apply
+        backup=apply(args.app,args.candidate,args.current_sha,args.candidate_sha)
+        print("Applied file. Rollback backup: " + backup)
+        print("Restart the app to load it. Review auth/source/network changes before launch."); return
+    if args.cmd == "config-schema":
+        from .configdoctor import editor_schema
+        print(json.dumps(editor_schema(), indent=2)); return
+    if args.cmd == "config-doctor":
+        from .configdoctor import report
+        if not report(args.app): raise SystemExit(1)
+        return
+    if args.cmd == "init":
+        if os.path.exists(args.name):
+            sys.exit("%s already exists" % args.name)
+        shutil.copytree(TEMPLATE, args.name, ignore=shutil.ignore_patterns("__pycache__", "*.db"))
+        print("Created %s/. Next: customchat run %s/app.yaml" % (args.name, args.name))
+    elif args.cmd == "export":
+        from .portable import export_app, ExportError
+        try:
+            m = export_app(args.app, args.output)
+        except (ExportError, OSError) as e:
+            sys.exit("Export stopped: %s" % e)
+        print("Exported %d app files to %s. No keys or private session state copied." % (len(m["files"]), args.output))
+        print("Review included local documents before sharing.")
+    elif args.cmd == "start":
+        from .launcher import start
+        start(args.directory, args.port, args.no_browser, args.lock_config)
+    elif args.cmd == "validate":
+        try:
+            c = schema.load(args.app)
+        except (schema.ConfigError, OSError) as e:
+            sys.exit("Invalid: %s" % e)
+        print("OK: %s, %d source(s), provider %s" % (c["app"]["title"], len(c["sources"]), c["provider"]["type"]))
+    elif args.cmd == "run":
+        from .server import serve
+        serve(args.app, args.host, args.port)
+    elif args.cmd == "doctor":
+        doctor(args.app)
+    elif args.cmd == "eval":
+        from .pipeline import Engine
+        from .store import Store
+        c = schema.load(args.app)
+        qs = [x.strip() for x in open(args.questions, encoding="utf-8") if x.strip() and not x.startswith("#")]
+        e = Engine(c, Store(":memory:"))
+        tot = cited = 0
+        for q in qs:
+            res = e.ask("eval", e.store.new_chat("eval"), q)
+            led = res["ledger"]; ok = sum(1 for l in led if l["supported"])
+            tot += len(led); cited += ok
+            print("%-60s evidence=%d claims=%d supported=%d" % (q[:60], len(res["evidence"]), len(led), ok))
+        print("coverage: %d/%d claims cited (%.0f%%)" % (cited, tot, 100.0 * cited / tot if tot else 0))
+    elif args.cmd == "ask":
+        from .pipeline import Engine
+        from .store import Store
+        c = schema.load(args.app)
+        e = Engine(c, Store(":memory:"))
+        res = e.ask("local", e.store.new_chat("local"), args.question)
+        if args.json:
+            print(json.dumps({k: res[k] for k in ("question", "standalone", "answer", "evidence", "ledger")}, indent=2)); return
+        print(res["answer"])
+        for ev in res["evidence"]:
+            print("  [%d] %s %s" % (ev["n"], ev["title"], ev["url"]))
+
+
+def doctor(path):
+    c = schema.load(path)
+    p = c["provider"]
+    print("provider:", p["type"], p["model"])
+    if p["type"] == "ollama":
+        base = (p["base_url"] or os.environ.get("OLLAMA_BASE_URL") or "http://localhost:11434").rstrip("/")
+        try:
+            tags = json.loads(urllib.request.urlopen(base + "/api/tags", timeout=5).read())
+            names = [m["name"] for m in tags.get("models", [])]
+            ok = any(n == p["model"] or n.startswith(p["model"] + ":") for n in names)
+            print("  ollama reachable; model %s %s" % (p["model"], "installed" if ok else "NOT installed, run: ollama pull " + p["model"]))
+        except Exception as e:
+            print("  ollama NOT reachable at %s (%s). Install from https://ollama.com and run `ollama serve`." % (base, type(e).__name__))
+    elif p["api_key_env"]:
+        print("  key env %s: %s" % (p["api_key_env"], "set" if os.environ.get(p["api_key_env"]) else "NOT set"))
+    from .connectors import make_connector
+    for s in c["sources"]:
+        try:
+            conn = make_connector(s, c["_dir"])
+            n = len(getattr(conn, "docs", [])) if s["type"] == "local_files" else None
+            print("  source %s (%s): ready%s" % (s["id"], s["type"], "" if n is None else ", %d chunks" % n))
+        except Exception as e:
+            print("  source %s: FAILED %s" % (s["id"], e))
+
+
+if __name__ == "__main__":
+    main()

customchat_app-0.1.0/customchat/configchange.py

@@ -0,0 +1,46 @@
+"""Offline config comparison and revision-checked replacement with private backup."""
+import hashlib, os, tempfile, time
+from pathlib import Path
+from .configdoctor import inspect
+from .schema import ConfigError
+
+def digest(path):return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+def checked(path):
+    issues,cfg=inspect(path)
+    if issues:raise ConfigError('Config has errors; run config-doctor first.')
+    return cfg
+
+def diff(current,candidate):
+    a,b=checked(current),checked(candidate);changes=[]
+    labels={'provider':'model behavior or remote requests','sources':'retrieval corpus/access','auth':'visitor access','prompt':'answer behavior','budget':'request/model quotas','storage':'saved data location','server':'network exposure','memory':'conversation context','citations':'evidence display','retrieval':'ranking/cache behavior','app':'brand/UI','schema_version':'config compatibility'}
+    def walk(a,b,key=''):
+        if isinstance(a,dict) and isinstance(b,dict):
+            for k in sorted(set(a)|set(b)):
+                walk(a.get(k),b.get(k),(key+'.' if key else '')+str(k))
+        elif a!=b:
+            changes.append({'key':key,'effect':labels.get(key.split('.')[0],'configuration')})
+    walk(a,b)
+    return {'current_sha256':digest(current),'candidate_sha256':digest(candidate),'changes':changes}
+
+def apply(current,candidate,current_sha,candidate_sha):
+    """Never copies .env or state, never follows a target symlink, no hot reload."""
+    dst,src=Path(current),Path(candidate)
+    if dst.is_symlink() or src.is_symlink():raise ConfigError('Use regular config files, not symlinks.')
+    checked(dst);checked(src)
+    old,new=dst.read_bytes(),src.read_bytes()
+    if hashlib.sha256(old).hexdigest()!=current_sha or hashlib.sha256(new).hexdigest()!=candidate_sha:
+        raise ConfigError('Config changed since preview. Run config-diff again.')
+    if old==new:raise ConfigError('No file change to apply.')
+    name=dst.with_name(dst.name+'.backup-'+str(time.time_ns()))
+    fd=os.open(str(name),os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+    with os.fdopen(fd,'wb') as f:f.write(old);f.flush();os.fsync(f.fileno())
+    fd,tmp=tempfile.mkstemp(prefix='.'+dst.name+'.',dir=str(dst.parent))
+    try:
+        with os.fdopen(fd,'wb') as f:f.write(new);f.flush();os.fsync(f.fileno())
+        # Catch edits during backup creation. This is not a multi-writer lock.
+        if dst.is_symlink() or digest(dst)!=current_sha:raise ConfigError('Current file changed; replacement stopped. Backup retained.')
+        os.replace(tmp,dst)
+    finally:
+        if os.path.exists(tmp):os.unlink(tmp)
+    return str(name)