carefold 0.5.0b1__tar.gz

carefold-0.5.0b1/.gitignore

@@ -0,0 +1,266 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+/MANIFEST
+backend/MANIFEST
+!packages/runner/src/manifest/
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Database & SQLite files:
+*.log
+*.db
+*.db-*
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+catalog.db*
+checkpoints.db*
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+.carefold.pids
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs and Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+tempCodeRunnerFile.py
+
+# Multi-Agent & Teamwork Runtime Artifacts
+.agents/
+.teamwork/
+teamwork/
+
+# Test Outputs & Coverage
+tests/e2e/results.json
+results.json
+.pytest_cache/
+backend/.pytest_cache/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Node.js & Package Managers
+node_modules/
+.pnpm-store/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-debug.log*
+
+# TypeScript & Build Outputs
+dist/
+build/
+*.tsbuildinfo
+.tsbuildinfo/
+out/
+.turbo/
+
+# Next.js
+.next/
+apps/web/.next/
+apps/web/out/
+
+# Carefold Local Runtime Workspace (User Data & Logs)
+/logs/
+/attachments/
+/chats/
+/chat/
+/notes/
+/workspace/
+carefold.config.json
+
+# Environment variables
+.env*.local
+
+# OS Artifacts
+.DS_Store
+Thumbs.db
+
+# UI Redesign assets & mockups
+/assets/carefold-ui-redesign/
+/assets/carefold-autonomy

carefold-0.5.0b1/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: carefold
+Version: 0.5.0b1
+Summary: Carefold local-first AI and agentic runtime backend
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: deepagents>=0.7
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fhir-resources>=8.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: langchain-anthropic>=0.3.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-google-genai>=2.0.0
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: pwdlib[argon2]>=0.2.0
+Requires-Dist: pydantic-handlebars>=0.2.1
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: spector-client>=0.1.0a4
+Requires-Dist: sqlalchemy[asyncio]>=2.0.35
+Requires-Dist: sse-starlette>=2.1.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: yarvelle-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: hatchling>=1.25.0; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: licenseheaders>=0.8.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Provides-Extra: ocr
+Requires-Dist: pillow>=10.0.0; extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+<!--
+  Carefold — Healthcare AI Agent Marketplace & Runtime
+  Copyright 2026 Spectrayan (https://spectrayan.com)
+
+  Licensed under the PolyForm Noncommercial License 1.0.0 and the
+  Carefold Additional Terms (see LICENSE and ADDITIONAL-TERMS.md).
+  Personal and household local use only. Commercial use, hosted service
+  offering, rebranding, white-labeling, and redistribution of modified
+  forks are prohibited without a written commercial license from Spectrayan.
+
+  Required Notice: Copyright 2026 Spectrayan (https://spectrayan.com)
+-->
+
+<h1 align="center">Carefold</h1>
+
+<p align="center">
+  <strong>Local-First Personal & Family Health AI Companion & Specialist Runtime.</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-PolyForm_Noncommercial_+_Additional_Terms-047857.svg?style=for-the-badge" alt="License" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.12-3776AB.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22_LTS-339933.svg?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node" /></a>
+  <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16_Turbopack-000000.svg?style=for-the-badge&logo=nextdotjs&logoColor=white" alt="Next.js" /></a>
+  <a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.115-009688.svg?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI" /></a>
+  <a href="docker/docker-compose.yml"><img src="https://img.shields.io/badge/Docker-Compose-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker Compose" /></a>
+  <a href="https://github.com/spectrayan/carefold/actions"><img src="https://img.shields.io/github/actions/workflow/status/spectrayan/carefold/ci.yml?branch=main&style=for-the-badge" alt="Build" /></a>
+  <a href="https://spectrayan.github.io/carefold/"><img src="https://img.shields.io/badge/Docs-MkDocs-blue?logo=materialformkdocs&style=for-the-badge" alt="Docs" /></a>
+</p>
+
+<p align="center">
+  <em>"Great care starts with prepared patients and supported families. Carefold brings local-first AI to your household—helping you organize records, prepare thoughtful questions for your care team, and navigate coverage with clarity and privacy."</em>
+</p>
+
+---
+
+**Carefold** is a source-available, local-first personal and family health AI companion and specialist agent runtime. Designed to work alongside your doctors, care teams, and health plans, Carefold runs on your own hardware (or private household instance) to help you prepare for clinical visits, organize health records and vitals across family members, track preventive screenings and pediatric school forms, and understand health insurance benefits.
+
+It pairs a **5-phase LangGraph orchestration engine** with **23 specialist clinical and administrative navigators**, **24 modular skill packs**, multi-profile household care with per-profile AES-256-GCM envelope encryption, scoped health and calendar connectors (`Epic SMART on FHIR`, `Withings`, `Google Calendar`, `CalDAV`, `Apple Health`, `FHIR R4`, `C-CDA`), multilingual support (`en-US`, `es-ES`, `fr-FR`, `hi-IN`, `ar-SA` with `RTL`), and a two-tier clinical safety guardrail system.
+
+<details>
+  <summary>📸 <strong>Preview Carefold Web Marketplace UI</strong> (Click to expand)</summary>
+  <br />
+  <p align="center">
+    <img src="assets/carefold-marketplace-preview.png" alt="Carefold Web Marketplace UI" width="100%" />
+  </p>
+</details>
+
+---
+
+## ⚡ 30-Second Quickstart
+
+Get a local Carefold runtime and household companion running in seconds:
+
+### 1. Instant Launch via Prebuilt Docker Container
+Run Carefold with a single command using the published multi-architecture image (supports Apple Silicon `arm64` and Intel/AMD `amd64` automatically):
+
+```bash
+# Pull and start the all-in-one container (Next.js UI on :3000, FastAPI backend on :8000)
+docker pull ghcr.io/spectrayan/carefold:latest
+
+# Run container (connecting to local Ollama on your host machine)
+docker run -d \
+  --name carefold \
+  -p 3000:3000 \
+  -p 8000:8000 \
+  -e OLLAMA_URL=http://host.docker.internal:11434/v1 \
+  -v carefold-data:/data \
+  ghcr.io/spectrayan/carefold:latest
+```
+Visit `http://localhost:3000` to browse specialist helpers and launch private household consultations.
+
+> [!TIP]
+> - **Connecting to Ollama on host**: On Docker Desktop (macOS / Windows), use `-e OLLAMA_URL=http://host.docker.internal:11434/v1` so the container can reach your host machine's Ollama instance.
+> - **Legacy tags on Apple Silicon**: If pulling older single-architecture tags (e.g. `0.3.0-beta.1`), append `--platform linux/amd64` to `docker pull` and `docker run`.
+
+### 2. Launch via Docker Compose (Build from Source)
+Images can also be built locally from [`docker/Dockerfile`](docker/Dockerfile):
+
+```bash
+# From the repository root: build and start the FastAPI backend (:8000) and Next.js UI (:3000)
+docker compose -f docker/docker-compose.yml up -d --build
+
+# Or also start a local Ollama container for on-device LLM inference:
+docker compose -f docker/docker-compose.yml --profile ollama up -d --build
+
+# Pull the default model into the Ollama container (first run only)
+docker compose -f docker/docker-compose.yml exec ollama ollama pull llama3.2
+```
+Visit `http://localhost:3000` to browse specialist helpers and launch private consultations.
+
+### 3. Local Monorepo Development
+
+**Prerequisites**: Python 3.12+ (tested on 3.12 and 3.14), Node.js 22 LTS, and `pnpm` (>=9.0.0).
+
+```bash
+# Clone repository
+git clone https://github.com/spectrayan/carefold.git
+cd carefold
+
+# Install frontend dependencies
+pnpm install
+
+# Set up backend environment
+python3 -m venv backend/.venv
+source backend/.venv/bin/activate
+pip install -e backend
+pip install -r backend/requirements-dev.txt
+
+# Start backend server (Terminal 1)
+uvicorn carefold.main:app --host 127.0.0.1 --port 8000 --reload
+
+# Start Next.js UI (Terminal 2)
+pnpm --filter web dev
+```
+
+---
+
+## 🏥 Specialist Agent Topology
+
+Carefold features a modular catalog of 23 specialist clinical and administrative navigators, organized into three core domains:
+
+- **Clinical Organ & Specialty Navigators (`clinical_assist`)**: Dedicated navigators for Cardiology, Pulmonology, Gastroenterology, Oncology, Neurology, Nephrology, Dermatology, Endocrinology, Orthopedics, Rheumatology, Urology, ENT, Vision, Hematology, Podiatry, Vascular Medicine, Oral Health, and General Visit Preparation. Each specialist helps you organize symptoms, review lab trends and vital signs, and prepare clear, prioritized questions to discuss with your clinician.
+- **Administrative & Insurance Stewards (`admin`)**: Stewards for Health Insurance Benefits & Coverage explanation, Prior Authorization preparation, Claims & Denials Appeals, Prescription Drug Formularies, and Multi-Provider Medical Records coordination.
+- **Wellness & Habit Companions (`wellness`)**: Daily companions for chronic care routines, hydration tracking, sleep hygiene, and lifestyle check-ins.
+
+### Exploring Available Agents
+
+You can explore, search, and interact with all specialist agents through:
+- **Web Consultation Studio**: Launch the web app (`pnpm dev:web` at `http://localhost:3000`) to browse and chat with any specialist helper.
+- **Living Documentation Catalog**: Read [`docs/agents/catalog.md`](docs/agents/catalog.md) for detailed descriptions, taxonomy classifications, and key capabilities.
+- **Carefold CLI & API**: Run `carefold list` or query `GET /api/agents` to inspect the runtime catalog programmatically.
+
+### System Infrastructure Agents (`agents/_system`)
+* **`orchestrator`**: Two-hop intent classification, dynamic skill provisioning, and multi-topology dispatch.
+* **`document-extractor`**: Ingestion sandbox, PII sanitization, structured Pydantic extraction, and numerical grounding validation.
+* **`quality-reviewer`**: Clinical safety boundary audit, tone inspection, and persona alignment verification.
+* **`triage-auditor`**: Compliance logging, risk tagging, and clinical safety telemetry.
+* **`skill-generator`**: Synthesis of dynamic skill manifests and validation templates from clinical guidelines.
+* **`suggestion-generator`**: Context-aware follow-up suggestion chips presented in the client UI.
+
+---
+
+## 🧠 Cognitive Memory, Hybrid Retrieval & Household Isolation
+
+Carefold implements a hexagonal architecture for memory, search, and household data isolation:
+
+* **Per-Profile Household Scoping & Envelope Encryption**: Every family member profile (`Self`, `Child`, `Parent`, `Spouse`) is isolated at the database, Content-Addressed Storage (`CAS`), and cryptographic levels using per-profile `HKDF-SHA256` / `AES-256-GCM` Data Encryption Keys (`ADR-0005`, `ADR-0007`).
+* **`MemoryPort` & 3-Tier Consolidation**: Cognitive memory interface supporting working, episodic, and semantic memory tiers with salience ranking and decay (`ADR-0002`).
+* **Hybrid `SearchIndex`**: Combines SQLite `FTS5` lexical BM25 search with `sqlite-vec` dense embeddings, Reciprocal Rank Fusion (`RRF`), and Maximal Marginal Relevance (`MMR`).
+* **End-to-End Internationalization (`ADR-0009`)**: Supports `en-US`, `es-ES`, `fr-FR`, `hi-IN`, and `ar-SA` (`RTL`) with IETF BCP 47 locale negotiation, Unicode UAX #15 `NFC` canonical storage normalization, HL7 FHIR R4 language-neutral clinical coding, and localized safety disclaimers.
+
+---
+
+## 🛡️ Two-Tier Clinical Safety, Policy Gates & Sandboxed Security
+
+Carefold enforces strict safety invariants to protect families and ensure non-clinical boundaries:
+
+### 1. Two-Tier Clinical Boundary System
+* **Tier 1 (Multilingual Emergency Red Flags)**: Instant termination with `911`/`988`/`112` emergency escalation when acute symptoms are detected across supported languages (e.g., crushing chest pain, acute stroke FAST symptoms, anaphylaxis, severe respiratory distress, or active self-harm crisis).
+* **Tier 2 (Collaborative Clinical Preparation)**: Helps patients organize questions and records for their licensed healthcare providers while never diagnosing conditions, prescribing medications, or adjusting dosages.
+
+### 2. Four-Tier Policy Gate & Zero-Trust Sandbox (`ADR-0004`)
+* **4-Tier Tool Execution Gate**: Classifies every tool into `read`, `write_local`, `write_external`, or `irreversible` across user-selectable autonomy levels (`A0` Manual, `A1` Assisted, `A2` Routine) with monotone taint tracking (`UntrustedResult`) and SHA-256 hash-chained `audit_events`.
+* **Path Traversal & Symlink Shield**: Strict lexical normalization and containment checks preventing `../` traversal, null bytes, and symlink escapes across `attachments/` and `workspace/notes/`.
+* **47-Attack Penetration Test Suite**: Automated security verification covering path traversal, command injection, symlink overwrites, and unauthorized skill access.
+
+---
+
+## 🚀 Quality Gates & Verification Matrix
+
+Carefold maintains rigorous verification standards across all code changes:
+
+```bash
+# 1. Spectrayan License Header Check
+pnpm run check:licenses
+
+# 2. Backend Pytest Suite
+PYTHONPATH=backend/src:libs/connectors backend/.venv/bin/pytest backend/tests/ libs/connectors/tests/
+
+# 3. Security Penetration Suite (47 Attack Vectors)
+PYTHONPATH=backend/src backend/.venv/bin/python backend/tests/penetration_suite.py
+
+# 4. Frontend Typecheck
+pnpm --filter web typecheck
+
+# 5. Frontend Unit & Component Tests
+pnpm --filter web test --exclude "**/api/**"
+
+# 6. Frontend Production Build
+pnpm --filter web build
+```
+
+---
+
+## 📜 Architecture Decision Records (ADRs)
+
+Carefold documents all major architectural decisions in [`docs/adr/`](docs/adr/):
+* [ADR 0001: Orchestrator-Driven Agent Architecture](docs/adr/0001-orchestrator-driven-agent-architecture.md)
+* [ADR 0002: Hexagonal Memory and Catalog Ports](docs/adr/0002-hexagonal-memory-and-catalog-ports.md)
+* [ADR 0003: Progressive Disclosure & Skill Context Management](docs/adr/0003-progressive-disclosure-skill-context-management.md)
+* [ADR 0004: Tool Execution Gate, 4-Tier Risk Approvals & Taint Propagation](docs/adr/0004-tool-execution-gate-and-taint-propagation.md)
+* [ADR 0005: Keyring Vault & Per-Profile Envelope Encryption](docs/adr/0005-keyring-vault-and-envelope-encryption.md)
+* [ADR 0006: Deployment Modes (Mode L Local vs Mode S Shared Household)](docs/adr/0006-deployment-modes-and-security-posture.md)
+* [ADR 0007: Partitioned Content-Addressed Storage & Hybrid Search Index](docs/adr/0007-partitioned-cas-and-hybrid-search.md)
+* [ADR 0008: Scoped Connectors, OAuth Bounce Relay & Taint Tracking](docs/adr/0008-scoped-connectors-and-taint-tracking.md)
+* [ADR 0009: End-to-End Internationalization & Multilingual Architecture](docs/adr/0009-internationalization-and-multilingual-architecture.md)
+
+---
+
+## 👥 Contributors
+
+Thank you to all the contributors who help build and improve Carefold!
+
+<p align="left">
+  <a href="https://github.com/spectrayan/carefold/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=spectrayan/carefold" alt="Carefold Contributors" />
+  </a>
+</p>
+
+---
+
+## 📄 License, Personal/Household Terms & Trademarks
+
+Carefold is **source-available** software licensed under the **[PolyForm Noncommercial License 1.0.0](LICENSE)** together with the **[Carefold Additional Terms](ADDITIONAL-TERMS.md)** and the **[Carefold Trademark Policy](TRADEMARKS.md)**:
+
+- **Permitted (Free Personal & Household Local Use)**: You may install, run, study, and modify Carefold for **personal and family use** on your own local hardware or private household instance, and contribute improvements back to the official repository under the **[Carefold Individual CLA](CLA.md)**.
+- **Prohibited Without a Commercial License**: Selling, reselling, offering Carefold as a hosted service (SaaS/API/portal), deploying inside any business or healthcare organization, **rebranding or white-labeling**, removing Carefold/Spectrayan attribution, or redistributing modified forks outside your household is strictly prohibited.
+- **Commercial Licensing**: For commercial, clinical, enterprise, or OEM licensing inquiries, contact `licensing@spectrayan.com`.
+
+See [`LICENSE`](LICENSE), [`ADDITIONAL-TERMS.md`](ADDITIONAL-TERMS.md), [`TRADEMARKS.md`](TRADEMARKS.md), [`CLA.md`](CLA.md), and [`NOTICE`](NOTICE) for full terms.
+
+Required Notice: Copyright © 2026 Spectrayan (https://spectrayan.com). All rights reserved.