jsat 0.1.0__py3-none-any.whl

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/_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"]

jsat/_ai/anthropic.py

@@ -0,0 +1,80 @@
+"""jsat._ai.anthropic — Anthropic/Claude AI provider (jsat[anthropic] extra)."""
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import TYPE_CHECKING, Iterator
+
+from jsat._ai import AIProvider
+from jsat._exceptions import AIAuthError, AIRateLimitError, AITimeoutError, ProfileError
+
+if TYPE_CHECKING:
+    from jsat._models import JSATConfig
+
+
+class AnthropicProvider(AIProvider):
+    """AI provider backed by the Anthropic SDK."""
+
+    def __init__(self, cfg: JSATConfig) -> None:
+        import structlog
+        self._log = structlog.get_logger(__name__)
+        try:
+            import anthropic as _anthropic
+            self._anthropic = _anthropic
+        except ImportError as e:
+            raise ProfileError(
+                "Anthropic SDK not installed.\nInstall: pip install 'jsat[anthropic]'",
+                required_extra="anthropic",
+            ) from e
+
+        self._model: str = cfg.ai.model or "claude-sonnet-4-6"
+        api_key_env = cfg.ai.api_key_env or "ANTHROPIC_API_KEY"
+        self._client = self._anthropic.Anthropic(api_key=os.environ.get(api_key_env))
+        self._log.info("anthropic_init", model=self._model,
+                       api_key_set=bool(os.environ.get(api_key_env)))
+
+    @property
+    def provider_name(self) -> str:
+        return "anthropic"
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    def complete(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        self._log.debug("anthropic_complete", prompt_len=len(prompt), max_tokens=max_tokens)
+        t0 = time.monotonic()
+        try:
+            resp = self._client.messages.create(
+                model=self._model, max_tokens=max_tokens, temperature=temperature,
+                messages=[{"role": "user", "content": prompt}],
+            )
+        except self._anthropic.RateLimitError as e:
+            raise AIRateLimitError("Anthropic rate limit", provider="anthropic") from e
+        except self._anthropic.AuthenticationError as e:
+            raise AIAuthError(provider="anthropic") from e
+        except self._anthropic.APITimeoutError as e:
+            raise AITimeoutError("Anthropic timeout", provider="anthropic",
+                                  timeout_seconds=120) from e
+        elapsed = round((time.monotonic() - t0) * 1000)
+        text: str = resp.content[0].text
+        self._log.info("anthropic_complete_done", response_len=len(text), duration_ms=elapsed)
+        return text
+
+    async def complete_async(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        return await asyncio.to_thread(self.complete, prompt, max_tokens, temperature)
+
+    def stream(self, prompt: str, max_tokens: int = 2048) -> Iterator[str]:
+        with self._client.messages.stream(
+            model=self._model, max_tokens=max_tokens,
+            messages=[{"role": "user", "content": prompt}],
+        ) as s:
+            yield from s.text_stream
+
+    def is_available(self) -> bool:
+        try:
+            self._client.models.list()
+            return True
+        except Exception:
+            return False

jsat/_ai/claude_cli.py

@@ -0,0 +1,278 @@
+"""
+jsat._ai.claude_cli — Full Claude CLI integration.
+
+Uses the real 'claude' binary with:
+  --resume <session-id>   → multi-turn conversation with full history
+  --system-prompt         → inject codebase context
+  --add-dir <repo>        → claude can read/write files in the project
+  --output-format stream-json → real streaming
+  --model <model>         → model selection
+
+This gives ALL claude CLI features inside jsat shell:
+  ✓ Multi-turn conversation memory
+  ✓ File reading / writing (Claude's Edit/Read tools)
+  ✓ Bash execution (Claude's Bash tool)
+  ✓ Model selection
+  ✓ All claude slash commands
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+import subprocess
+import time
+from typing import Iterator
+
+from jsat._ai import AIProvider
+
+
+class ClaudeCliProvider(AIProvider):
+    """Full-featured Claude CLI provider with session continuity."""
+
+    def __init__(self, cfg=None) -> None:
+        import structlog
+        self._log = structlog.get_logger(__name__)
+
+        self._binary = shutil.which("claude") or "claude"
+        self._model = getattr(getattr(cfg, "ai", None), "model", None) or "claude-sonnet-4-6"
+        self._timeout = getattr(getattr(cfg, "ai", None), "timeout_seconds", None) or 180
+
+        # Session state
+        self._session_id: str | None = None
+        self._call_count: int = 0
+        self._repo_dir: str | None = None
+        self._system_prompt: str | None = None
+        # stateful=False (default): each call independent — for MCP server
+        # stateful=True: uses --continue for multi-turn — for interactive shell
+        self._stateful: bool = False
+
+        if not shutil.which("claude"):
+            self._log.warning(
+                "claude_cli_not_found",
+                message="'claude' binary not in PATH. Install: https://claude.ai/code",
+            )
+        else:
+            self._log.info("claude_cli_init", binary=self._binary, model=self._model)
+
+    # ── Configuration (called by JSATShell before first message) ─────────────
+
+    def configure(self, repo_dir: str | None = None,
+                  system_prompt: str | None = None,
+                  stateful: bool = True) -> None:
+        """Inject repo context and enable stateful (multi-turn) mode.
+
+        Call this from the interactive shell before the first complete().
+        Do NOT call from the MCP server — MCP uses stateless mode by default.
+        """
+        self._repo_dir = repo_dir
+        self._system_prompt = system_prompt
+        self._stateful = stateful
+
+    def new_session(self) -> None:
+        """Start a fresh conversation (clears history)."""
+        self._session_id = None
+        self._call_count = 0
+        self._log.info("claude_cli_new_session")
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    # ── AIProvider interface ──────────────────────────────────────────────────
+
+    @property
+    def provider_name(self) -> str:
+        return "claude_cli"
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    def is_available(self) -> bool:
+        return bool(shutil.which("claude"))
+
+    def _build_args(self, prompt: str, stream: bool = False) -> list[str]:
+        """Build the full claude CLI command for this call.
+
+        Two modes:
+          stateless (default, used by MCP server): each call is independent.
+            Claude Code maintains conversation context itself.
+          stateful (enabled by configure()): uses --continue to resume the
+            last conversation. Used by the interactive jsat shell.
+        """
+        args = [self._binary]
+
+        # Print mode (non-interactive)
+        args += ["-p", prompt]
+
+        # Output format
+        if stream:
+            args += ["--output-format", "stream-json"]
+        else:
+            args += ["--output-format", "text"]
+
+        # Model selection — only pass --model for known Claude model names.
+        # Never pass Ollama/GPT model names (e.g. "llama3.2") to the claude CLI.
+        _CLAUDE_MODELS = {
+            "claude-sonnet-4-6", "claude-haiku-4-5-20251001", "claude-opus-4-8",
+            "claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022",
+            "claude-3-opus-20240229",
+        }
+        if self._model and self._model in _CLAUDE_MODELS and self._model != "claude-sonnet-4-6":
+            args += ["--model", self._model]
+
+        if self._stateful:
+            # Stateful mode (interactive shell): maintain conversation history.
+            # Use --continue on calls after the first to resume the last session.
+            if self._call_count == 0:
+                # First call: inject context
+                if self._system_prompt:
+                    args += ["--system-prompt", self._system_prompt]
+                if self._repo_dir:
+                    args += ["--add-dir", self._repo_dir]
+            else:
+                # Continue the last conversation in this directory
+                args += ["--continue"]
+        else:
+            # Stateless mode (MCP server default): each call is independent.
+            # Claude Code handles conversation context via its own history.
+            # Do NOT use --session-id or --resume — they cause "Invalid session ID".
+            if self._system_prompt:
+                args += ["--append-system-prompt", self._system_prompt]
+            if self._repo_dir:
+                args += ["--add-dir", self._repo_dir]
+
+        return args
+
+    def complete(self, prompt: str, max_tokens: int = 8192,
+                 temperature: float = 0.1) -> str:
+        import structlog
+        log = structlog.get_logger(__name__)
+
+        if not shutil.which("claude"):
+            raise RuntimeError(
+                "'claude' CLI not found. Install Claude Code: https://claude.ai/code"
+            )
+
+        args = self._build_args(prompt, stream=False)
+        log.debug("claude_cli_complete",
+                  session=self._session_id, call=self._call_count,
+                  prompt_len=len(prompt))
+
+        t0 = time.monotonic()
+        try:
+            result = subprocess.run(
+                args,
+                capture_output=True, text=True, timeout=self._timeout,
+            )
+        except subprocess.TimeoutExpired:
+            from jsat._exceptions import AITimeoutError
+            raise AITimeoutError(
+                f"claude timed out after {self._timeout}s",
+                provider="claude_cli", timeout_seconds=self._timeout,
+            )
+
+        elapsed = round((time.monotonic() - t0) * 1000)
+
+        if result.returncode != 0:
+            stderr = result.stderr.strip()
+            log.error("claude_cli_error", returncode=result.returncode,
+                      stderr=stderr[:300], elapsed_ms=elapsed)
+            raise RuntimeError(
+                f"claude exited {result.returncode}: {stderr[:200]}"
+            )
+
+        self._call_count += 1
+        text = result.stdout.strip()
+        log.info("claude_cli_done", response_len=len(text), elapsed_ms=elapsed,
+                 session=self._session_id, turn=self._call_count)
+        return text
+
+    async def complete_async(self, prompt: str, max_tokens: int = 8192,
+                             temperature: float = 0.1) -> str:
+        return await asyncio.to_thread(self.complete, prompt, max_tokens, temperature)
+
+    def stream(self, prompt: str, max_tokens: int = 8192) -> Iterator[str]:
+        """Stream response using --output-format stream-json (NDJSON events)."""
+        import structlog
+        log = structlog.get_logger(__name__)
+
+        if not shutil.which("claude"):
+            raise RuntimeError("'claude' CLI not found.")
+
+        args = self._build_args(prompt, stream=True)
+        log.debug("claude_cli_stream_start",
+                  session=self._session_id, call=self._call_count)
+
+        t0 = time.monotonic()
+        total_chars = 0
+
+        try:
+            proc = subprocess.Popen(
+                args,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+            assert proc.stdout is not None
+
+            for raw_line in proc.stdout:
+                line = raw_line.strip()
+                if not line:
+                    continue
+
+                # Parse the stream-json NDJSON event
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    # Plain text fallback (some claude versions)
+                    yield raw_line
+                    total_chars += len(raw_line)
+                    continue
+
+                event_type = event.get("type", "")
+
+                # Text delta — the actual streamed content
+                if event_type == "content_block_delta":
+                    delta = event.get("delta", {})
+                    if delta.get("type") == "text_delta":
+                        text = delta.get("text", "")
+                        if text:
+                            yield text
+                            total_chars += len(text)
+
+                # assistant message block (non-streaming text)
+                elif event_type == "assistant":
+                    for block in event.get("message", {}).get("content", []):
+                        if block.get("type") == "text":
+                            text = block.get("text", "")
+                            if text:
+                                yield text
+                                total_chars += len(text)
+
+                # Result event — session ID may be updated here
+                elif event_type == "result":
+                    sid = event.get("session_id")
+                    if sid:
+                        self._session_id = sid
+
+            proc.wait(timeout=10)
+
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            from jsat._exceptions import AITimeoutError
+            raise AITimeoutError(
+                f"claude stream timed out after {self._timeout}s",
+                provider="claude_cli", timeout_seconds=self._timeout,
+            )
+        except Exception as e:
+            log.error("claude_cli_stream_error", error=str(e))
+            raise
+
+        self._call_count += 1
+        elapsed = round((time.monotonic() - t0) * 1000)
+        log.info("claude_cli_stream_done",
+                 total_chars=total_chars, elapsed_ms=elapsed,
+                 session=self._session_id, turn=self._call_count)

jsat/_ai/none.py

@@ -0,0 +1,60 @@
+"""jsat._ai.none — No-op AIProvider for CI mode."""
+from __future__ import annotations
+
+from typing import Iterator
+
+from jsat._ai import AIProvider
+
+_warned = False
+_MSG = (
+    "No AI provider configured. "
+    "Set ai.provider in .jsat.yaml or run: jsat init --profile solo"
+)
+
+
+def _warn_once() -> None:
+    global _warned
+    if _warned:
+        return
+    _warned = True
+    import structlog
+    structlog.get_logger(__name__).warning("noop_ai_provider_active", message=_MSG)
+
+
+def _ai_error() -> type[Exception]:
+    try:
+        from jsat._exceptions import AIError
+        return AIError
+    except ImportError:
+        return RuntimeError
+
+
+class NoOpProvider(AIProvider):
+    """No-op provider — raises AIError on every call. Used in CI mode."""
+
+    @property
+    def provider_name(self) -> str:
+        return "none"
+
+    @property
+    def model_name(self) -> str:
+        return "none"
+
+    def is_available(self) -> bool:
+        return False
+
+    def complete(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        _warn_once()
+        raise _ai_error()(_MSG)
+
+    async def complete_async(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        _warn_once()
+        raise _ai_error()(_MSG)
+
+    def stream(self, prompt: str, max_tokens: int = 2048) -> Iterator[str]:
+        _warn_once()
+        return
+        yield
+
+
+__all__ = ["NoOpProvider"]

jsat/_ai/ollama.py

@@ -0,0 +1,97 @@
+"""jsat._ai.ollama — Ollama AI provider (jsat[local] extra)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any, Iterator
+
+from jsat._ai import AIProvider
+
+if TYPE_CHECKING:
+    from jsat._models import JSATConfig
+
+
+class OllamaProvider(AIProvider):
+    """AI provider backed by a local Ollama instance."""
+
+    def __init__(self, cfg: JSATConfig) -> None:
+        import structlog
+        self._log = structlog.get_logger(__name__)
+
+        try:
+            import ollama as _ollama  # type: ignore[import]
+            self._ollama = _ollama
+        except ImportError as e:
+            from jsat._exceptions import ProfileError
+            raise ProfileError(
+                "Ollama package not installed.\nInstall: pip install 'jsat[local]'",
+                required_extra="local",
+            ) from e
+
+        ai = cfg.ai
+        self._model: str = getattr(ai, "model", None) or "llama3.2"
+        self._base_url: str = getattr(ai, "base_url", None) or "http://localhost:11434"
+        self._max_tokens: int = getattr(ai, "max_tokens", 8192)
+        self._timeout: int = getattr(ai, "timeout_seconds", 120)
+
+        self._log.info("ollama_init", model=self._model, base_url=self._base_url)
+
+    @property
+    def provider_name(self) -> str:
+        return "ollama"
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    def complete(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        self._log.debug("ollama_complete", prompt_len=len(prompt), max_tokens=max_tokens)
+        t0 = time.monotonic()
+        try:
+            resp = self._ollama.generate(
+                model=self._model, prompt=prompt,
+                options={"num_predict": max_tokens, "temperature": temperature},
+            )
+        except Exception as e:
+            elapsed = round((time.monotonic() - t0) * 1000)
+            self._log.error("ollama_complete_error", error=str(e), elapsed_ms=elapsed)
+            from jsat._exceptions import AIProviderError
+            raise AIProviderError(
+                f"Ollama error: {e}", provider="ollama", status_code=0
+            ) from e
+
+        elapsed = round((time.monotonic() - t0) * 1000)
+        text: str = resp["response"]
+        self._log.info("ollama_complete_done", response_len=len(text), duration_ms=elapsed)
+        return text
+
+    async def complete_async(self, prompt: str, max_tokens: int = 2048, temperature: float = 0.1) -> str:
+        return await asyncio.to_thread(self.complete, prompt, max_tokens, temperature)
+
+    def stream(self, prompt: str, max_tokens: int = 2048) -> Iterator[str]:
+        self._log.debug("ollama_stream_start", prompt_len=len(prompt))
+        total = 0
+        try:
+            for chunk in self._ollama.generate(
+                model=self._model, prompt=prompt,
+                options={"num_predict": max_tokens}, stream=True,
+            ):
+                piece: str = chunk.get("response", "")
+                if piece:
+                    total += len(piece)
+                    yield piece
+        except Exception as e:
+            self._log.error("ollama_stream_error", error=str(e), chars_so_far=total)
+            raise
+        self._log.info("ollama_stream_done", total_chars=total)
+
+    def is_available(self) -> bool:
+        try:
+            import httpx
+            resp = httpx.get(f"{self._base_url}/api/tags", timeout=0.5)
+            up = resp.status_code < 500
+            self._log.debug("ollama_available", up=up, status=resp.status_code)
+            return up
+        except Exception as e:
+            self._log.debug("ollama_unavailable", error=str(e))
+            return False