jsat 0.1.0__tar.gz

jsat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install jsat (core + standard, no AI backends)
+        run: uv pip install --system -e ".[standard]"
+
+      - name: Run CI-safe tests
+        run: pytest -m ci --tb=short -q
+        env:
+          CI: "true"
+
+      - name: Coverage report (Python 3.11 only)
+        if: matrix.python-version == '3.11'
+        run: |
+          uv pip install --system coverage
+          coverage run -m pytest -m ci -q
+          coverage report --fail-under=55
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint
+        run: ruff check jsat/ --select E,F,I --ignore E501,E402

jsat-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"          # triggers on: git tag v0.1.0 && git push --tags
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/jsat/
+
+    permissions:
+      id-token: write   # required for trusted publishing (no token needed!)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+        # To set the secret:
+        # 1. pypi.org → Account Settings → API tokens → Add token (Entire account)
+        # 2. GitHub repo → Settings → Secrets and variables → Actions → New secret
+        #    Name: PYPI_API_TOKEN   Value: pypi-AgEI...

jsat-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Planning docs (local only — not tracked)
+plan.md
+prompt.md
+
+# JSAT — everything lives under .jsat/
+# Exclude runtime artifacts; keep config.yaml committable for team sharing
+.jsat/graph/
+.jsat/vectors/
+.jsat/cache/
+.jsat/system-profile.json
+.jsat/audit.log
+# Legacy root-level config (no longer created)
+.jsat.yaml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*venv/
+
+# Node
+node_modules/
+
+# Editors
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Secrets (never commit)
+*.pem
+*.key
+.env.local

jsat-0.1.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to JSAT.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-25
+
+### Added
+
+**Core infrastructure**
+- 27-class exception hierarchy (`JSATError` → `ConfigError`, `IndexError`, `AIError`, `GraphError`, `ProfileError`, `ExportError`, `SkillError`) — all with structured context kwargs
+- All Pydantic v2 models: `JSATConfig`, `SystemProfile`, `IndexResult`, `BlastRadiusReport`, `SecurityReport`, `IncidentReport`, `QueryResult`, `ExportManifest`, and supporting sub-models
+- Config loader with 5-path search order + `CI=true` auto-overrides
+- System auto-detection: RAM, CPU arch (arm64/x86_64), GPU (CUDA/Metal/none), service reachability (Ollama, Neo4j, Qdrant, Redis)
+- Profile presets: `solo`, `team`, `ci`, `raspberry-pi`
+
+**JSAT class and CLI**
+- `JSAT` class with fully lazy backend wiring — heavy imports only on first call
+- Typer CLI: `jsat index`, `jsat shell`, `jsat doctor`, `jsat init`, `jsat export`, `jsat import`, `jsat skills list/run`, `jsat version`
+
+**Tools (0–14)**
+- Tool 0 — JSAT Shell: interactive REPL with 14 commands, tab completion, session history, Rich output
+- Tool 1 — Directory Indexer: tree-sitter AST parsing (Python, JS/TS, Go), BFS graph population, `INDEX.md` output
+- Tool 2 — Test Intelligence Helper: source-to-test file matching, over-mock detection, behavioral coverage estimate
+- Tool 3 — Feature Helper: graph-context-aware implementation plan generation
+- Tool 4 — Blast Radius Analyzer: BFS traversal with severity classification (breaking/degraded/warning/safe) and Mermaid diagram output
+- Tool 5 — API Contract Validator: OpenAPI/AsyncAPI diff between git branches with compatibility score
+- Tool 6 — Security Review Agent: Semgrep integration (graceful fallback), Shannon entropy secret detection, OWASP severity filtering
+- Tool 7 — Incident Investigation Helper: git history scoring with recency × blast-radius × pattern-match formula
+- Tool 8 — Migration Safety Validator: SQL parsing, lock-type classification, zero-downtime guide generation
+- Tool 9 — Multi-Model Code Review: parallel dispatch, embedding-based deduplication, confidence ranking
+- Tool 10 — Knowledge Base Builder: graph-stored knowledge entries, AI synthesis, stale-flag decay
+- Tool 11 — Multi-Agent Orchestrator: heuristic task decomposition, sequential agent execution, conflict detection
+- Tool 12 — Export / Import System: atomic ZIP export with manifest, graph + artifact restore
+- Tool 13 — Python SDK: `JSAT` class; full sync + async API for all tools
+- Tool 14 — IThinking: 7-phase meta-cognitive wrapper (intent → plan → verify → execute → reflect)
+
+**Backends**
+- Graph: SQLite (core, always available), LightGraph (stdlib-only fallback), Neo4j (team extra)
+- Embeddings: NoOp/zero-vector (CI), local Ollama nomic-embed-code, OpenAI text-embedding-3-*
+- Cache: memory LRU, atomic disk JSON, Redis (team extra)
+- AI: NoOp (CI), Ollama (local), Anthropic/Claude, OpenAI, any OpenAI-compatible endpoint
+
+**MCP server**
+- JSON-RPC 2.0 stdin/stdout server with 47-tool catalog (JSON Schema per tool)
+- 12 tool categories: Index, Blast Radius, Tests, Security, API Contract, Knowledge, Incident, Migration, Review, Export, Meta, IThinking
+
+**Skills system**
+- `SkillsRegistry`: YAML manifest auto-discovery and dispatch
+- `SkillManifest` Pydantic model with `from_yaml()` and `to_mcp_tool()` converters
+- 7 built-in skill clusters: `start-session`, `new-feature`, `pre-merge`, `incident`, `security-release`, `db-schema-change`, `knowledge-maintenance`
+
+**Tests**
+- 43+ CI-safe tests (`@pytest.mark.ci`) covering: exceptions, models, caches, SQLite graph, parsers (Python/JS/Go), blast radius, incident scoring, migration analysis, security detection, skills registry
+
+**Packaging**
+- `pyproject.toml` with 6 pip extras: `core` (~80MB), `local`, `standard`, `team`, `ci`, `all`
+- GitHub Actions CI: matrix (Python 3.10/3.11/3.12), ruff lint, coverage gate at 55%

jsat-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: jsat
+Version: 0.1.0
+Summary: JaySoft AI Tools — open-source codebase intelligence shell and SDK
+Project-URL: Homepage, https://github.com/jsat-project/jsat
+Project-URL: Repository, https://github.com/jsat-project/jsat
+Project-URL: Bug Tracker, https://github.com/jsat-project/jsat/issues
+Author-email: JaySoft <iamjpsonkar@gmail.com>
+License: MIT
+Keywords: ai,cli,codebase,intelligence,sdk,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8
+Requires-Dist: gitpython>=3.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: sqlean-py>=0.21.7
+Requires-Dist: structlog>=24
+Requires-Dist: tree-sitter-go>=0.21
+Requires-Dist: tree-sitter-javascript>=0.21
+Requires-Dist: tree-sitter-python>=0.21
+Requires-Dist: tree-sitter>=0.21
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30; extra == 'all'
+Requires-Dist: graphiti-core>=0.3; extra == 'all'
+Requires-Dist: jsonschema>=4.20; extra == 'all'
+Requires-Dist: neo4j>=5.15; extra == 'all'
+Requires-Dist: ollama>=0.2; extra == 'all'
+Requires-Dist: openai>=1.35; extra == 'all'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'all'
+Requires-Dist: prance>=23; extra == 'all'
+Requires-Dist: pygithub>=2; extra == 'all'
+Requires-Dist: qdrant-client>=1.7; extra == 'all'
+Requires-Dist: redis>=5; extra == 'all'
+Requires-Dist: sarif-tools>=0.3; extra == 'all'
+Requires-Dist: semgrep>=1.50; extra == 'all'
+Requires-Dist: tree-sitter-java>=0.21; extra == 'all'
+Requires-Dist: tree-sitter-ruby>=0.21; extra == 'all'
+Requires-Dist: tree-sitter-rust>=0.21; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: ci
+Requires-Dist: jsonschema>=4.20; extra == 'ci'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'ci'
+Requires-Dist: prance>=23; extra == 'ci'
+Requires-Dist: pygithub>=2; extra == 'ci'
+Requires-Dist: sarif-tools>=0.3; extra == 'ci'
+Requires-Dist: semgrep>=1.50; extra == 'ci'
+Requires-Dist: tree-sitter-java>=0.21; extra == 'ci'
+Requires-Dist: tree-sitter-ruby>=0.21; extra == 'ci'
+Requires-Dist: tree-sitter-rust>=0.21; extra == 'ci'
+Provides-Extra: local
+Requires-Dist: ollama>=0.2; extra == 'local'
+Provides-Extra: openai
+Requires-Dist: openai>=1.35; extra == 'openai'
+Provides-Extra: standard
+Requires-Dist: jsonschema>=4.20; extra == 'standard'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'standard'
+Requires-Dist: prance>=23; extra == 'standard'
+Requires-Dist: semgrep>=1.50; extra == 'standard'
+Requires-Dist: tree-sitter-java>=0.21; extra == 'standard'
+Requires-Dist: tree-sitter-ruby>=0.21; extra == 'standard'
+Requires-Dist: tree-sitter-rust>=0.21; extra == 'standard'
+Provides-Extra: team
+Requires-Dist: graphiti-core>=0.3; extra == 'team'
+Requires-Dist: jsonschema>=4.20; extra == 'team'
+Requires-Dist: neo4j>=5.15; extra == 'team'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'team'
+Requires-Dist: prance>=23; extra == 'team'
+Requires-Dist: qdrant-client>=1.7; extra == 'team'
+Requires-Dist: redis>=5; extra == 'team'
+Requires-Dist: semgrep>=1.50; extra == 'team'
+Requires-Dist: tree-sitter-java>=0.21; extra == 'team'
+Requires-Dist: tree-sitter-ruby>=0.21; extra == 'team'
+Requires-Dist: tree-sitter-rust>=0.21; extra == 'team'
+Description-Content-Type: text/markdown
+
+# JSAT — JaySoft AI Tools
+
+> Codebase intelligence shell and SDK. Lightweight by default.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Author](https://img.shields.io/badge/author-Jay%20Prakash%20Sonkar-green.svg)](https://github.com/iamjpsonkar)
+
+## What is JSAT?
+
+JSAT gives any AI (Claude, Codex, Gemini, or local Ollama) deep, structured understanding of
+your codebase — so you spend less time explaining context and more time shipping.
+
+- **Interactive shell** like IPython, but for codebase intelligence
+- **Python SDK** — `from jsat import JSAT`
+- **Works offline** with local Ollama — no API keys required
+- **Lightweight by default** — `pip install jsat` is ~80MB and starts in <800ms
+
+## Quick Start
+
+```bash
+pip install jsat          # core only
+pip install jsat[local]   # + Ollama for local AI (recommended)
+
+cd your-project/
+jsat init --profile solo  # write .jsat.yaml
+jsat index .              # build the codebase graph
+jsat                      # start the shell
+```
+
+```
+JSAT Shell v0.1.0
+> what does this project do?
+> which services write to the orders table?
+> blast-radius src/payment/refund.py
+```
+
+## Installation Profiles
+
+| Profile | Command | Size | Use case |
+|---------|---------|------|---------|
+| Core | `pip install jsat` | ~80MB | Quick evaluation |
+| Local AI | `pip install jsat[local]` | ~85MB | Solo dev with Ollama |
+| Standard | `pip install jsat[standard]` | ~120MB | Individual engineers |
+| Team | `pip install jsat[team]` | ~200MB | Engineering teams |
+| CI | `pip install jsat[ci]` | ~90MB | CI pipelines (no AI cost) |
+| Full | `pip install jsat[all]` | ~350MB | Power users |
+
+## System Auto-Detection
+
+JSAT probes your machine on first run and selects the right backends:
+
+```bash
+jsat doctor   # see what's detected and what to install
+```
+
+| Your setup | Graph | Embeddings | Cache |
+|-----------|-------|-----------|-------|
+| Laptop, Ollama running | SQLite | nomic-embed-code (local) | disk |
+| Team server (Neo4j+Qdrant+Redis) | Neo4j | text-embedding-3-small | Redis |
+| ARM (Apple M2, Pi) | SQLite | nomic-embed-code via Metal | disk |
+| CI environment | SQLite | none (skipped) | memory |
+
+## Python SDK
+
+```python
+from jsat import JSAT
+
+js = JSAT(repo=".")
+js.index()
+
+# Natural language query
+result = js.query("what calls the refund endpoint?")
+print(result.answer)
+
+# Blast radius — trace impact of a change
+report = js.blast_radius("src/payment/refund.py")
+for impact in report.impacts:
+    print(f"{impact.severity}: {impact.node_name}")
+
+# Incident investigation
+incident = js.investigate_incident("500 errors on checkout since 14:00")
+for h in incident.hypotheses:
+    print(f"Score {h.score}: {h.commit_summary}")
+
+# Export for sharing
+js.export("backup.jsat.zip")
+```
+
+## CLI Reference
+
+```bash
+jsat index [PATH] [--branch HEAD] [--force]
+jsat shell
+jsat doctor [--refresh] [--json]
+jsat init --profile solo|team|ci|raspberry-pi
+jsat export OUTPUT
+jsat import ARCHIVE
+jsat skills list
+jsat version
+```
+
+## Architecture
+
+JSAT is built around a **graph-native architecture**:
+
+- **tree-sitter** for multi-language AST parsing
+- **SQLite** (local) or **Neo4j** (team) for the codebase graph
+- **Ollama** (local) or any cloud LLM for AI features
+- **Lazy loading** — nothing heavy loads until you use it
+
+All backends implement ABCs — tools never call backends directly.
+
+## Project
+
+- **Author:** Jay Prakash Sonkar ([@iamjpsonkar](https://github.com/iamjpsonkar))
+- **Email:** iamjpsonkar@gmail.com
+- **License:** MIT
+- **Specification:** [`plan.md`](plan.md) | **Implementation guide:** [`prompt.md`](prompt.md)

jsat-0.1.0/README.md

@@ -0,0 +1,119 @@
+# JSAT — JaySoft AI Tools
+
+> Codebase intelligence shell and SDK. Lightweight by default.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Author](https://img.shields.io/badge/author-Jay%20Prakash%20Sonkar-green.svg)](https://github.com/iamjpsonkar)
+
+## What is JSAT?
+
+JSAT gives any AI (Claude, Codex, Gemini, or local Ollama) deep, structured understanding of
+your codebase — so you spend less time explaining context and more time shipping.
+
+- **Interactive shell** like IPython, but for codebase intelligence
+- **Python SDK** — `from jsat import JSAT`
+- **Works offline** with local Ollama — no API keys required
+- **Lightweight by default** — `pip install jsat` is ~80MB and starts in <800ms
+
+## Quick Start
+
+```bash
+pip install jsat          # core only
+pip install jsat[local]   # + Ollama for local AI (recommended)
+
+cd your-project/
+jsat init --profile solo  # write .jsat.yaml
+jsat index .              # build the codebase graph
+jsat                      # start the shell
+```
+
+```
+JSAT Shell v0.1.0
+> what does this project do?
+> which services write to the orders table?
+> blast-radius src/payment/refund.py
+```
+
+## Installation Profiles
+
+| Profile | Command | Size | Use case |
+|---------|---------|------|---------|
+| Core | `pip install jsat` | ~80MB | Quick evaluation |
+| Local AI | `pip install jsat[local]` | ~85MB | Solo dev with Ollama |
+| Standard | `pip install jsat[standard]` | ~120MB | Individual engineers |
+| Team | `pip install jsat[team]` | ~200MB | Engineering teams |
+| CI | `pip install jsat[ci]` | ~90MB | CI pipelines (no AI cost) |
+| Full | `pip install jsat[all]` | ~350MB | Power users |
+
+## System Auto-Detection
+
+JSAT probes your machine on first run and selects the right backends:
+
+```bash
+jsat doctor   # see what's detected and what to install
+```
+
+| Your setup | Graph | Embeddings | Cache |
+|-----------|-------|-----------|-------|
+| Laptop, Ollama running | SQLite | nomic-embed-code (local) | disk |
+| Team server (Neo4j+Qdrant+Redis) | Neo4j | text-embedding-3-small | Redis |
+| ARM (Apple M2, Pi) | SQLite | nomic-embed-code via Metal | disk |
+| CI environment | SQLite | none (skipped) | memory |
+
+## Python SDK
+
+```python
+from jsat import JSAT
+
+js = JSAT(repo=".")
+js.index()
+
+# Natural language query
+result = js.query("what calls the refund endpoint?")
+print(result.answer)
+
+# Blast radius — trace impact of a change
+report = js.blast_radius("src/payment/refund.py")
+for impact in report.impacts:
+    print(f"{impact.severity}: {impact.node_name}")
+
+# Incident investigation
+incident = js.investigate_incident("500 errors on checkout since 14:00")
+for h in incident.hypotheses:
+    print(f"Score {h.score}: {h.commit_summary}")
+
+# Export for sharing
+js.export("backup.jsat.zip")
+```
+
+## CLI Reference
+
+```bash
+jsat index [PATH] [--branch HEAD] [--force]
+jsat shell
+jsat doctor [--refresh] [--json]
+jsat init --profile solo|team|ci|raspberry-pi
+jsat export OUTPUT
+jsat import ARCHIVE
+jsat skills list
+jsat version
+```
+
+## Architecture
+
+JSAT is built around a **graph-native architecture**:
+
+- **tree-sitter** for multi-language AST parsing
+- **SQLite** (local) or **Neo4j** (team) for the codebase graph
+- **Ollama** (local) or any cloud LLM for AI features
+- **Lazy loading** — nothing heavy loads until you use it
+
+All backends implement ABCs — tools never call backends directly.
+
+## Project
+
+- **Author:** Jay Prakash Sonkar ([@iamjpsonkar](https://github.com/iamjpsonkar))
+- **Email:** iamjpsonkar@gmail.com
+- **License:** MIT
+- **Specification:** [`plan.md`](plan.md) | **Implementation guide:** [`prompt.md`](prompt.md)

jsat-0.1.0/jsat/__init__.py

@@ -0,0 +1,38 @@
+"""
+JSAT — JaySoft AI Tools
+Codebase intelligence shell and SDK. Lightweight by default.
+
+  pip install jsat           # core only (~80MB)
+  pip install jsat[local]    # + Ollama
+  pip install jsat[standard] # + analysis tools
+  pip install jsat[team]     # + Neo4j, Qdrant, Redis
+  pip install jsat[all]      # everything
+"""
+from __future__ import annotations
+
+from jsat._core import JSAT
+from jsat._config import load_config
+from jsat._exceptions import (
+    JSATError, ConfigError, ConfigFileNotFound, ConfigSchemaError,
+    MissingRequiredConfig, IndexError, IndexNotFound, IndexCorrupted,
+    IndexOutOfDate, UnsupportedLanguage, AIError, AIProviderError,
+    AIRateLimitError, AITimeoutError, AIContextLengthError, AIAuthError,
+    GraphError, GraphConnectionError, GraphQueryError, GraphCapacityError,
+    ProfileError, ExportError, ExportPermissionError, ImportVersionMismatch,
+    ImportCorrupted, SkillError, SkillNotFound, SkillManifestError,
+    SkillExecutionError,
+)
+
+__version__ = "0.1.0"
+__author__ = "Jay Prakash Sonkar"
+__email__ = "iamjpsonkar@gmail.com"
+__license__ = "MIT"
+
+__all__ = [
+    "JSAT",
+    "load_config",
+    "JSATError",
+    "__version__",
+    "__author__",
+    "__email__",
+]

jsat-0.1.0/jsat/_ai/__init__.py

@@ -0,0 +1,90 @@
+"""jsat._ai — AIProvider ABC and factory."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Iterator
+
+
+class AIProvider(ABC):
+    """Contract all AI/LLM backends must implement."""
+
+    @abstractmethod
+    def complete(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str: ...
+
+    @abstractmethod
+    async def complete_async(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str: ...
+
+    @abstractmethod
+    def stream(self, prompt: str, max_tokens: int = 2048) -> Iterator[str]: ...
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str: ...
+
+    def is_available(self) -> bool:
+        return True
+
+
+def get_ai_provider(cfg: Any) -> AIProvider:
+    """Factory: returns the right AIProvider based on cfg.ai.provider."""
+    import structlog
+    log = structlog.get_logger(__name__)
+
+    provider_name: str = getattr(getattr(cfg, "ai", None), "provider", "none") or "none"
+    log.info("ai_provider_factory", provider=provider_name)
+
+    if provider_name == "none":
+        from jsat._ai.none import NoOpProvider
+        return NoOpProvider()
+
+    if provider_name == "claude_cli":
+        from jsat._ai.claude_cli import ClaudeCliProvider
+        return ClaudeCliProvider(cfg)
+
+    if provider_name == "ollama":
+        try:
+            from jsat._ai.ollama import OllamaProvider
+            return OllamaProvider(cfg)
+        except ImportError as e:
+            _profile_error("ollama", "local", e)
+
+    if provider_name == "anthropic":
+        try:
+            from jsat._ai.anthropic import AnthropicProvider  # type: ignore[import]
+            return AnthropicProvider(cfg)
+        except ImportError as e:
+            _profile_error("anthropic", "anthropic", e)
+
+    if provider_name == "openai":
+        try:
+            from jsat._ai.openai import OpenAIProvider  # type: ignore[import]
+            return OpenAIProvider(cfg)
+        except ImportError as e:
+            _profile_error("openai", "openai", e)
+
+    raise ValueError(
+        f"Unknown ai.provider '{provider_name}'. "
+        "Valid: none, ollama, anthropic, openai. Run: jsat init --profile solo"
+    )
+
+
+def _profile_error(provider: str, extra: str, cause: ImportError) -> None:
+    import structlog
+    structlog.get_logger(__name__).error(
+        "ai_provider_import_failed", provider=provider, extra=extra, error=str(cause)
+    )
+    try:
+        from jsat._exceptions import ProfileError
+        raise ProfileError(
+            f"AI provider '{provider}' requires jsat[{extra}].\n"
+            f"Install: pip install 'jsat[{extra}]'"
+        ) from cause
+    except ImportError:
+        raise ImportError(f"Install: pip install 'jsat[{extra}]'") from cause
+
+
+__all__ = ["AIProvider", "get_ai_provider"]