javaxFlash 2.1.0__tar.gz

javaxflash-2.1.0/LICENSE

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

javaxflash-2.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: javaxFlash
+Version: 2.1.0
+Summary: Lightweight local-first AI router with javaxFlash and DeepSeek.
+Author: Javas Antony
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/javaxFlash/
+Keywords: ai,client,router,gemini,deepseek
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# javaxFlash
+
+`javaxFlash` adalah library Python kecil untuk mengakses beberapa endpoint AI lewat satu client API yang sederhana.
+
+Tujuan library ini:
+
+- memberi satu entry point yang ringan: `FlashClient`
+- memudahkan pindah antara provider `flash` dan `deepseek`
+- mendukung auto routing atau provider manual
+- mengembalikan format respons yang konsisten
+
+## Cocok untuk apa
+
+- pertanyaan cepat dengan provider default `flash`
+- prompt reasoning yang lebih berat dengan `deepseek`
+- eksperimen lokal tanpa harus menulis wrapper request berulang-ulang
+
+## Install
+
+Install package inti:
+
+```bash
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Kalau ingin menjalankan contoh interaktif di folder `examples`, install juga `rich`:
+
+```bash
+python -m pip install rich
+```
+
+## Quick Start
+
+Contoh paling sederhana:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+
+response = client.flash("Jelaskan konsep Q-learning dengan sederhana")
+
+print(response.text)
+print(response.provider)
+print(response.model_used)
+```
+
+Alias `ask()` juga tersedia:
+
+```python
+response = client.ask("Apa itu Python?")
+print(response.text)
+```
+
+## Cara Kerja Singkat
+
+Secara default, `FlashClient` akan:
+
+1. menerima prompt dari user
+2. memilih provider berdasarkan mode atau auto routing
+3. mengirim request ke endpoint provider
+4. mengembalikan hasil dalam bentuk `FlashResponse`
+
+Kalau provider utama gagal dan fallback aktif, client akan mencoba provider cadangan.
+
+## Memilih Provider
+
+### 1. Auto routing
+
+Auto routing cocok kalau kamu ingin library memilih provider secara otomatis.
+
+```python
+response = client.flash("Bandingkan REST dan GraphQL untuk project kecil", auto_route=True)
+```
+
+### 2. Fast mode
+
+Gunakan saat ingin jawaban cepat.
+
+```python
+response = client.flash("Apa itu Python?", mode="fast")
+```
+
+### 3. Reasoning mode
+
+Gunakan saat prompt butuh analisis lebih dalam.
+
+```python
+response = client.flash("Kenapa algoritma ini gagal dan bagaimana cara debug-nya?", mode="reasoning")
+```
+
+### 4. Paksa provider tertentu
+
+Kalau kamu sudah tahu provider mana yang ingin dipakai:
+
+```python
+response = client.flash("Gunakan provider cepat", provider="flash")
+response = client.flash("Analisis bug ini", provider="deepseek")
+```
+
+## Konfigurasi Dasar
+
+Kalau ingin mengubah perilaku default client:
+
+```python
+from javaxFlash import FlashClient, FlashConfig
+
+config = FlashConfig(
+    timeout=30.0,
+    auto_route=True,
+    fallback_enabled=True,
+    default_system_instruction="You are javaxFlash, a concise and practical AI assistant.",
+)
+
+client = FlashClient(config=config)
+```
+
+Field config yang paling sering dipakai:
+
+- `timeout`: timeout request HTTP
+- `auto_route`: aktif/nonaktif routing otomatis
+- `fallback_enabled`: coba provider cadangan saat request gagal
+- `default_system_instruction`: system prompt default
+- `default_gemini_model`: nama model untuk provider `flash`
+- `deepseek_temperature`: temperature default untuk DeepSeek
+- `debug`: tampilkan log sederhana saat development
+- `request_logging`: aktifkan logging request
+
+## Custom System Instruction
+
+Kamu bisa memberi system instruction per request:
+
+```python
+response = client.flash(
+    "Bantu saya menyusun rencana automation",
+    system_instruction="You are an AI assistant focused on backend automation and practical implementation.",
+)
+```
+
+Atau menjadikannya default lewat `FlashConfig`.
+
+## Response Object
+
+Setiap request mengembalikan `FlashResponse` dengan struktur yang konsisten:
+
+```python
+response.text
+response.model_used
+response.provider
+response.raw
+response.route_reason
+response.error
+```
+
+Penjelasan singkat:
+
+- `text`: isi jawaban utama
+- `model_used`: nama model yang dilaporkan provider
+- `provider`: provider yang benar-benar dipakai
+- `raw`: payload JSON mentah dari endpoint
+- `route_reason`: alasan routing yang dipilih client
+- `error`: pesan error jika request gagal
+
+Contoh:
+
+```python
+response = client.flash("Jelaskan recursion")
+
+if response.error:
+    print("Error:", response.error)
+else:
+    print(response.text)
+    print("Provider:", response.provider)
+    print("Reason:", response.route_reason)
+```
+
+## Parameter yang Bisa Dipakai Saat Request
+
+API utama:
+
+```python
+client.flash(
+    prompt,
+    mode=None,
+    provider=None,
+    auto_route=None,
+    system_instruction=None,
+    fallback_provider=None,
+    **kwargs,
+)
+```
+
+Parameter penting:
+
+- `prompt`: isi permintaan user
+- `mode`: `fast` atau `reasoning`
+- `provider`: paksa provider tertentu
+- `auto_route`: override perilaku routing default
+- `system_instruction`: system instruction per request
+- `fallback_provider`: provider cadangan jika request utama gagal
+- `**kwargs`: parameter tambahan yang diteruskan ke provider
+
+Contoh `kwargs`:
+
+```python
+response = client.flash(
+    "Jelaskan greedy algorithm",
+    provider="deepseek",
+    temperature=0.2,
+)
+```
+
+## Menjalankan Contoh Interaktif
+
+Contoh interaktif ada di `examples/basic_usage.py`.
+
+Jalankan dengan:
+
+```bash
+python examples/basic_usage.py
+```
+
+atau:
+
+```bash
+python -m examples.basic_usage
+```
+
+## Struktur Project
+
+File yang paling penting:
+
+- `javaxFlash/client.py`: entry point utama library
+- `javaxFlash/config.py`: konfigurasi client
+- `javaxFlash/router.py`: logika pemilihan provider
+- `javaxFlash/providers.py`: implementasi request ke provider
+- `javaxFlash/models.py`: model respons
+
+## Catatan Penting
+
+- `flash` di library ini adalah nama provider cepat yang dibacking oleh endpoint Gemini Lite.
+- `deepseek` dipakai untuk prompt yang lebih berat atau mode reasoning.
+- Output akhir tetap bergantung pada endpoint upstream yang dipanggil library ini.
+- Library ini sekarang stateless; tidak ada fitur memory atau penyimpanan percakapan lokal.
+
+## Minimal Example
+
+Kalau ingin contoh paling ringkas untuk dipakai di project lain:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+response = client.flash("Buat ringkasan tentang REST API", mode="fast")
+
+if response.error:
+    raise RuntimeError(response.error)
+
+print(response.text)
+```

javaxflash-2.1.0/README.md

@@ -0,0 +1,261 @@
+# javaxFlash
+
+`javaxFlash` adalah library Python kecil untuk mengakses beberapa endpoint AI lewat satu client API yang sederhana.
+
+Tujuan library ini:
+
+- memberi satu entry point yang ringan: `FlashClient`
+- memudahkan pindah antara provider `flash` dan `deepseek`
+- mendukung auto routing atau provider manual
+- mengembalikan format respons yang konsisten
+
+## Cocok untuk apa
+
+- pertanyaan cepat dengan provider default `flash`
+- prompt reasoning yang lebih berat dengan `deepseek`
+- eksperimen lokal tanpa harus menulis wrapper request berulang-ulang
+
+## Install
+
+Install package inti:
+
+```bash
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Kalau ingin menjalankan contoh interaktif di folder `examples`, install juga `rich`:
+
+```bash
+python -m pip install rich
+```
+
+## Quick Start
+
+Contoh paling sederhana:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+
+response = client.flash("Jelaskan konsep Q-learning dengan sederhana")
+
+print(response.text)
+print(response.provider)
+print(response.model_used)
+```
+
+Alias `ask()` juga tersedia:
+
+```python
+response = client.ask("Apa itu Python?")
+print(response.text)
+```
+
+## Cara Kerja Singkat
+
+Secara default, `FlashClient` akan:
+
+1. menerima prompt dari user
+2. memilih provider berdasarkan mode atau auto routing
+3. mengirim request ke endpoint provider
+4. mengembalikan hasil dalam bentuk `FlashResponse`
+
+Kalau provider utama gagal dan fallback aktif, client akan mencoba provider cadangan.
+
+## Memilih Provider
+
+### 1. Auto routing
+
+Auto routing cocok kalau kamu ingin library memilih provider secara otomatis.
+
+```python
+response = client.flash("Bandingkan REST dan GraphQL untuk project kecil", auto_route=True)
+```
+
+### 2. Fast mode
+
+Gunakan saat ingin jawaban cepat.
+
+```python
+response = client.flash("Apa itu Python?", mode="fast")
+```
+
+### 3. Reasoning mode
+
+Gunakan saat prompt butuh analisis lebih dalam.
+
+```python
+response = client.flash("Kenapa algoritma ini gagal dan bagaimana cara debug-nya?", mode="reasoning")
+```
+
+### 4. Paksa provider tertentu
+
+Kalau kamu sudah tahu provider mana yang ingin dipakai:
+
+```python
+response = client.flash("Gunakan provider cepat", provider="flash")
+response = client.flash("Analisis bug ini", provider="deepseek")
+```
+
+## Konfigurasi Dasar
+
+Kalau ingin mengubah perilaku default client:
+
+```python
+from javaxFlash import FlashClient, FlashConfig
+
+config = FlashConfig(
+    timeout=30.0,
+    auto_route=True,
+    fallback_enabled=True,
+    default_system_instruction="You are javaxFlash, a concise and practical AI assistant.",
+)
+
+client = FlashClient(config=config)
+```
+
+Field config yang paling sering dipakai:
+
+- `timeout`: timeout request HTTP
+- `auto_route`: aktif/nonaktif routing otomatis
+- `fallback_enabled`: coba provider cadangan saat request gagal
+- `default_system_instruction`: system prompt default
+- `default_gemini_model`: nama model untuk provider `flash`
+- `deepseek_temperature`: temperature default untuk DeepSeek
+- `debug`: tampilkan log sederhana saat development
+- `request_logging`: aktifkan logging request
+
+## Custom System Instruction
+
+Kamu bisa memberi system instruction per request:
+
+```python
+response = client.flash(
+    "Bantu saya menyusun rencana automation",
+    system_instruction="You are an AI assistant focused on backend automation and practical implementation.",
+)
+```
+
+Atau menjadikannya default lewat `FlashConfig`.
+
+## Response Object
+
+Setiap request mengembalikan `FlashResponse` dengan struktur yang konsisten:
+
+```python
+response.text
+response.model_used
+response.provider
+response.raw
+response.route_reason
+response.error
+```
+
+Penjelasan singkat:
+
+- `text`: isi jawaban utama
+- `model_used`: nama model yang dilaporkan provider
+- `provider`: provider yang benar-benar dipakai
+- `raw`: payload JSON mentah dari endpoint
+- `route_reason`: alasan routing yang dipilih client
+- `error`: pesan error jika request gagal
+
+Contoh:
+
+```python
+response = client.flash("Jelaskan recursion")
+
+if response.error:
+    print("Error:", response.error)
+else:
+    print(response.text)
+    print("Provider:", response.provider)
+    print("Reason:", response.route_reason)
+```
+
+## Parameter yang Bisa Dipakai Saat Request
+
+API utama:
+
+```python
+client.flash(
+    prompt,
+    mode=None,
+    provider=None,
+    auto_route=None,
+    system_instruction=None,
+    fallback_provider=None,
+    **kwargs,
+)
+```
+
+Parameter penting:
+
+- `prompt`: isi permintaan user
+- `mode`: `fast` atau `reasoning`
+- `provider`: paksa provider tertentu
+- `auto_route`: override perilaku routing default
+- `system_instruction`: system instruction per request
+- `fallback_provider`: provider cadangan jika request utama gagal
+- `**kwargs`: parameter tambahan yang diteruskan ke provider
+
+Contoh `kwargs`:
+
+```python
+response = client.flash(
+    "Jelaskan greedy algorithm",
+    provider="deepseek",
+    temperature=0.2,
+)
+```
+
+## Menjalankan Contoh Interaktif
+
+Contoh interaktif ada di `examples/basic_usage.py`.
+
+Jalankan dengan:
+
+```bash
+python examples/basic_usage.py
+```
+
+atau:
+
+```bash
+python -m examples.basic_usage
+```
+
+## Struktur Project
+
+File yang paling penting:
+
+- `javaxFlash/client.py`: entry point utama library
+- `javaxFlash/config.py`: konfigurasi client
+- `javaxFlash/router.py`: logika pemilihan provider
+- `javaxFlash/providers.py`: implementasi request ke provider
+- `javaxFlash/models.py`: model respons
+
+## Catatan Penting
+
+- `flash` di library ini adalah nama provider cepat yang dibacking oleh endpoint Gemini Lite.
+- `deepseek` dipakai untuk prompt yang lebih berat atau mode reasoning.
+- Output akhir tetap bergantung pada endpoint upstream yang dipanggil library ini.
+- Library ini sekarang stateless; tidak ada fitur memory atau penyimpanan percakapan lokal.
+
+## Minimal Example
+
+Kalau ingin contoh paling ringkas untuk dipakai di project lain:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+response = client.flash("Buat ringkasan tentang REST API", mode="fast")
+
+if response.error:
+    raise RuntimeError(response.error)
+
+print(response.text)
+```

javaxflash-2.1.0/javaxFlash/__init__.py

@@ -0,0 +1,5 @@
+from .client import FlashClient
+from .config import FlashConfig
+from .models import FlashResponse
+
+__all__ = ["FlashClient", "FlashConfig", "FlashResponse"]

javaxflash-2.1.0/javaxFlash/client.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .config import FlashConfig
+from .models import FlashResponse
+from .providers import DeepSeekProvider, FlashProvider, ProviderError
+from .router import FlashRouter
+
+
+class FlashClient:
+    def __init__(self, config: FlashConfig | None = None):
+        self.config = config or FlashConfig()
+        self.router = FlashRouter()
+        self.providers = {
+            "deepseek": DeepSeekProvider(self.config),
+            "gemini": FlashProvider(self.config),
+            "flash": FlashProvider(self.config),
+        }
+
+    def flash(
+        self,
+        prompt: str,
+        *,
+        mode: str | None = None,
+        provider: str | None = None,
+        auto_route: bool | None = None,
+        system_instruction: str | None = None,
+        fallback_provider: str | None = None,
+        **kwargs: Any,
+    ) -> FlashResponse:
+        auto_route = self.config.auto_route if auto_route is None else auto_route
+        if provider == "flash":
+            provider = "gemini"
+        if fallback_provider == "flash":
+            fallback_provider = "gemini"
+        instruction = system_instruction or self.config.default_system_instruction
+
+        decision = self.router.choose(
+            prompt=prompt,
+            mode=mode,
+            forced_provider=provider,
+            auto_route=auto_route,
+            default_provider=self.config.default_provider,
+        )
+        chosen_provider = decision.provider
+
+        try:
+            response = self.providers[chosen_provider].request(
+                prompt,
+                system_prompt=instruction,
+                **kwargs,
+            )
+            response.route_reason = decision.reason
+            response.provider = "flash" if chosen_provider == "gemini" else chosen_provider
+        except ProviderError as exc:
+            if not self.config.fallback_enabled and not fallback_provider:
+                return self._error_response(chosen_provider, str(exc), decision.reason)
+            backup = fallback_provider or self._other_provider(chosen_provider)
+            try:
+                response = self.providers[backup].request(
+                    prompt,
+                    system_prompt=instruction,
+                    **kwargs,
+                )
+                response.route_reason = f"{decision.reason}; fallback to {backup} after {chosen_provider} failed"
+                response.provider = "flash" if backup == "gemini" else backup
+            except ProviderError as fallback_exc:
+                return self._error_response(
+                    chosen_provider,
+                    f"{exc} | fallback failed: {fallback_exc}",
+                    decision.reason,
+                )
+
+        return response
+
+    def ask(self, prompt: str, **kwargs: Any) -> FlashResponse:
+        return self.flash(prompt, **kwargs)
+
+    def _other_provider(self, provider: str) -> str:
+        return "gemini" if provider == "deepseek" else "deepseek"
+
+    def _error_response(
+        self,
+        provider: str,
+        error: str,
+        route_reason: str,
+    ) -> FlashResponse:
+        public_provider = "flash" if provider == "gemini" else provider
+        return FlashResponse(
+            text="",
+            model_used=self.config.default_model_name if public_provider == "flash" else provider,
+            provider=public_provider,
+            raw=None,
+            route_reason=route_reason,
+            error=error,
+        )
+
+
+AIClient = FlashClient

javaxflash-2.1.0/javaxFlash/config.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class FlashConfig:
+    timeout: float = 30.0
+    default_provider: str = "flash"
+    default_model_name: str = "javaxFlash"
+    default_gemini_model: str = "gemini-2.0-flash-lite"
+    deepseek_temperature: float = 0.7
+    auto_route: bool = True
+    debug: bool = False
+    request_logging: bool = False
+    fallback_enabled: bool = True
+    default_system_instruction: str = (
+        "You are javaxFlash, a practical, concise, and helpful AI assistant."
+    )
+
+
+AIClientConfig = FlashConfig

javaxflash-2.1.0/javaxFlash/models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class FlashResponse:
+    text: str
+    model_used: str
+    provider: str
+    raw: Any = None
+    route_reason: str = ""
+    error: str | None = None
+
+
+AIResponse = FlashResponse

javaxflash-2.1.0/javaxFlash/providers.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import requests
+
+from .config import FlashConfig
+from .models import FlashResponse
+
+
+class ProviderError(RuntimeError):
+    pass
+
+
+class BaseProvider(ABC):
+    name: str
+    endpoint: str
+
+    def __init__(self, config: FlashConfig):
+        self.config = config
+
+    @abstractmethod
+    def build_params(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def request(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        **kwargs: Any,
+    ) -> FlashResponse:
+        params = self.build_params(prompt=prompt, system_prompt=system_prompt, **kwargs)
+        self._log(f"[{self.name}] GET {self.endpoint} params={params}")
+        try:
+            response = requests.get(
+                self.endpoint,
+                params=params,
+                timeout=self.config.timeout,
+            )
+            response.raise_for_status()
+        except requests.Timeout as exc:
+            raise ProviderError(f"{self.name} request timed out after {self.config.timeout}s") from exc
+        except requests.RequestException as exc:
+            raise ProviderError(f"{self.name} request failed: {exc}") from exc
+
+        try:
+            raw = response.json()
+        except ValueError as exc:
+            raise ProviderError(f"{self.name} returned invalid JSON") from exc
+
+        text = self.extract_text(raw)
+        if not text:
+            raise ProviderError(f"{self.name} response did not contain usable text")
+
+        return FlashResponse(
+            text=text.strip(),
+            model_used=self.extract_model(raw, **kwargs),
+            provider=self.name,
+            raw=raw,
+        )
+
+    def extract_text(self, raw: Any) -> str:
+        if isinstance(raw, str):
+            return raw
+
+        if isinstance(raw, dict):
+            for key in ("text", "response", "answer", "result", "message", "content"):
+                value = raw.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value
+            data = raw.get("data")
+            if isinstance(data, dict):
+                for key in ("text", "response", "answer", "result", "message", "content"):
+                    value = data.get(key)
+                    if isinstance(value, str) and value.strip():
+                        return value
+                parts = data.get("parts")
+                if isinstance(parts, list):
+                    collected: list[str] = []
+                    for part in parts:
+                        if isinstance(part, dict):
+                            text = part.get("text")
+                            if isinstance(text, str) and text.strip():
+                                collected.append(text.strip())
+                    if collected:
+                        return "\n".join(collected)
+        return ""
+
+    def extract_model(self, raw: Any, **kwargs: Any) -> str:
+        if isinstance(raw, dict):
+            for key in ("model", "model_used"):
+                value = raw.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value
+        return kwargs.get("model", self.name)
+
+    def _log(self, message: str) -> None:
+        if self.config.debug or self.config.request_logging:
+            print(message)
+
+
+class DeepSeekProvider(BaseProvider):
+    name = "deepseek"
+    endpoint = "https://api.siputzx.my.id/api/ai/deepseekr1"
+
+    def build_params(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        temperature = kwargs.get("temperature", self.config.deepseek_temperature)
+        return {
+            "prompt": prompt,
+            "system": system_prompt or self.config.default_system_instruction,
+            "temperature": temperature,
+        }
+
+
+class FlashProvider(BaseProvider):
+    name = "flash"
+    endpoint = "https://api.siputzx.my.id/api/ai/gemini-lite"
+
+    def build_params(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        if system_prompt:
+            prompt = f"System instruction: {system_prompt}\n\nUser request: {prompt}"
+        return {
+            "prompt": prompt,
+            "model": kwargs.get("model", self.config.default_gemini_model),
+        }
+
+    def extract_model(self, raw: Any, **kwargs: Any) -> str:
+        value = super().extract_model(raw, **kwargs)
+        return self.config.default_model_name if value == self.name else value
+
+
+GeminiLiteProvider = FlashProvider

javaxflash-2.1.0/javaxFlash/router.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class RouteDecision:
+    provider: str
+    reason: str
+
+
+class FlashRouter:
+    COMPLEX_KEYWORDS = {
+        "debug",
+        "bug",
+        "error",
+        "reasoning",
+        "step-by-step",
+        "step by step",
+        "architecture",
+        "design",
+        "plan",
+        "strategy",
+        "analyze",
+        "analysis",
+        "compare",
+        "tradeoff",
+        "why",
+        "kenapa",
+        "mengapa",
+        "refactor",
+        "algorithm",
+        "infinite loop",
+        "q-learning",
+        "rl",
+        "root cause",
+    }
+    SIMPLE_PREFIXES = (
+        "apa ",
+        "what ",
+        "who ",
+        "when ",
+        "where ",
+        "define ",
+        "jelaskan singkat",
+        "summarize ",
+        "ringkas ",
+    )
+
+    def choose(
+        self,
+        prompt: str,
+        mode: str | None = None,
+        forced_provider: str | None = None,
+        auto_route: bool = True,
+        default_provider: str = "flash",
+    ) -> RouteDecision:
+        if forced_provider == "flash":
+            forced_provider = "gemini"
+
+        if forced_provider:
+            return RouteDecision(
+                provider=forced_provider,
+                reason=f"provider forced explicitly: {forced_provider}",
+            )
+
+        if mode == "reasoning":
+            return RouteDecision(provider="deepseek", reason="reasoning mode requested")
+        if mode == "fast":
+            return RouteDecision(provider="gemini", reason="fast mode requested (Flash)")
+
+        if not auto_route:
+            resolved = "gemini" if default_provider == "flash" else default_provider
+            return RouteDecision(
+                provider=resolved,
+                reason=f"auto routing disabled, using default provider {default_provider}",
+            )
+
+        normalized = prompt.strip().lower()
+        if any(token in normalized for token in self.COMPLEX_KEYWORDS):
+            return RouteDecision(
+                provider="deepseek",
+                reason="prompt contains complex reasoning/debugging keywords",
+            )
+        if len(normalized.split()) <= 12 or normalized.startswith(self.SIMPLE_PREFIXES):
+            return RouteDecision(
+                provider="gemini",
+                reason="prompt looks short or fact-oriented",
+            )
+        if "?" in normalized and len(normalized.split()) <= 20:
+            return RouteDecision(
+                provider="gemini",
+                reason="prompt looks like a quick question",
+            )
+        return RouteDecision(
+            provider="deepseek",
+            reason="defaulted to deeper reasoning for broader prompt",
+        )
+
+
+PromptRouter = FlashRouter

javaxflash-2.1.0/javaxFlash.egg-info/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: javaxFlash
+Version: 2.1.0
+Summary: Lightweight local-first AI router with javaxFlash and DeepSeek.
+Author: Javas Antony
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/javaxFlash/
+Keywords: ai,client,router,gemini,deepseek
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# javaxFlash
+
+`javaxFlash` adalah library Python kecil untuk mengakses beberapa endpoint AI lewat satu client API yang sederhana.
+
+Tujuan library ini:
+
+- memberi satu entry point yang ringan: `FlashClient`
+- memudahkan pindah antara provider `flash` dan `deepseek`
+- mendukung auto routing atau provider manual
+- mengembalikan format respons yang konsisten
+
+## Cocok untuk apa
+
+- pertanyaan cepat dengan provider default `flash`
+- prompt reasoning yang lebih berat dengan `deepseek`
+- eksperimen lokal tanpa harus menulis wrapper request berulang-ulang
+
+## Install
+
+Install package inti:
+
+```bash
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Kalau ingin menjalankan contoh interaktif di folder `examples`, install juga `rich`:
+
+```bash
+python -m pip install rich
+```
+
+## Quick Start
+
+Contoh paling sederhana:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+
+response = client.flash("Jelaskan konsep Q-learning dengan sederhana")
+
+print(response.text)
+print(response.provider)
+print(response.model_used)
+```
+
+Alias `ask()` juga tersedia:
+
+```python
+response = client.ask("Apa itu Python?")
+print(response.text)
+```
+
+## Cara Kerja Singkat
+
+Secara default, `FlashClient` akan:
+
+1. menerima prompt dari user
+2. memilih provider berdasarkan mode atau auto routing
+3. mengirim request ke endpoint provider
+4. mengembalikan hasil dalam bentuk `FlashResponse`
+
+Kalau provider utama gagal dan fallback aktif, client akan mencoba provider cadangan.
+
+## Memilih Provider
+
+### 1. Auto routing
+
+Auto routing cocok kalau kamu ingin library memilih provider secara otomatis.
+
+```python
+response = client.flash("Bandingkan REST dan GraphQL untuk project kecil", auto_route=True)
+```
+
+### 2. Fast mode
+
+Gunakan saat ingin jawaban cepat.
+
+```python
+response = client.flash("Apa itu Python?", mode="fast")
+```
+
+### 3. Reasoning mode
+
+Gunakan saat prompt butuh analisis lebih dalam.
+
+```python
+response = client.flash("Kenapa algoritma ini gagal dan bagaimana cara debug-nya?", mode="reasoning")
+```
+
+### 4. Paksa provider tertentu
+
+Kalau kamu sudah tahu provider mana yang ingin dipakai:
+
+```python
+response = client.flash("Gunakan provider cepat", provider="flash")
+response = client.flash("Analisis bug ini", provider="deepseek")
+```
+
+## Konfigurasi Dasar
+
+Kalau ingin mengubah perilaku default client:
+
+```python
+from javaxFlash import FlashClient, FlashConfig
+
+config = FlashConfig(
+    timeout=30.0,
+    auto_route=True,
+    fallback_enabled=True,
+    default_system_instruction="You are javaxFlash, a concise and practical AI assistant.",
+)
+
+client = FlashClient(config=config)
+```
+
+Field config yang paling sering dipakai:
+
+- `timeout`: timeout request HTTP
+- `auto_route`: aktif/nonaktif routing otomatis
+- `fallback_enabled`: coba provider cadangan saat request gagal
+- `default_system_instruction`: system prompt default
+- `default_gemini_model`: nama model untuk provider `flash`
+- `deepseek_temperature`: temperature default untuk DeepSeek
+- `debug`: tampilkan log sederhana saat development
+- `request_logging`: aktifkan logging request
+
+## Custom System Instruction
+
+Kamu bisa memberi system instruction per request:
+
+```python
+response = client.flash(
+    "Bantu saya menyusun rencana automation",
+    system_instruction="You are an AI assistant focused on backend automation and practical implementation.",
+)
+```
+
+Atau menjadikannya default lewat `FlashConfig`.
+
+## Response Object
+
+Setiap request mengembalikan `FlashResponse` dengan struktur yang konsisten:
+
+```python
+response.text
+response.model_used
+response.provider
+response.raw
+response.route_reason
+response.error
+```
+
+Penjelasan singkat:
+
+- `text`: isi jawaban utama
+- `model_used`: nama model yang dilaporkan provider
+- `provider`: provider yang benar-benar dipakai
+- `raw`: payload JSON mentah dari endpoint
+- `route_reason`: alasan routing yang dipilih client
+- `error`: pesan error jika request gagal
+
+Contoh:
+
+```python
+response = client.flash("Jelaskan recursion")
+
+if response.error:
+    print("Error:", response.error)
+else:
+    print(response.text)
+    print("Provider:", response.provider)
+    print("Reason:", response.route_reason)
+```
+
+## Parameter yang Bisa Dipakai Saat Request
+
+API utama:
+
+```python
+client.flash(
+    prompt,
+    mode=None,
+    provider=None,
+    auto_route=None,
+    system_instruction=None,
+    fallback_provider=None,
+    **kwargs,
+)
+```
+
+Parameter penting:
+
+- `prompt`: isi permintaan user
+- `mode`: `fast` atau `reasoning`
+- `provider`: paksa provider tertentu
+- `auto_route`: override perilaku routing default
+- `system_instruction`: system instruction per request
+- `fallback_provider`: provider cadangan jika request utama gagal
+- `**kwargs`: parameter tambahan yang diteruskan ke provider
+
+Contoh `kwargs`:
+
+```python
+response = client.flash(
+    "Jelaskan greedy algorithm",
+    provider="deepseek",
+    temperature=0.2,
+)
+```
+
+## Menjalankan Contoh Interaktif
+
+Contoh interaktif ada di `examples/basic_usage.py`.
+
+Jalankan dengan:
+
+```bash
+python examples/basic_usage.py
+```
+
+atau:
+
+```bash
+python -m examples.basic_usage
+```
+
+## Struktur Project
+
+File yang paling penting:
+
+- `javaxFlash/client.py`: entry point utama library
+- `javaxFlash/config.py`: konfigurasi client
+- `javaxFlash/router.py`: logika pemilihan provider
+- `javaxFlash/providers.py`: implementasi request ke provider
+- `javaxFlash/models.py`: model respons
+
+## Catatan Penting
+
+- `flash` di library ini adalah nama provider cepat yang dibacking oleh endpoint Gemini Lite.
+- `deepseek` dipakai untuk prompt yang lebih berat atau mode reasoning.
+- Output akhir tetap bergantung pada endpoint upstream yang dipanggil library ini.
+- Library ini sekarang stateless; tidak ada fitur memory atau penyimpanan percakapan lokal.
+
+## Minimal Example
+
+Kalau ingin contoh paling ringkas untuk dipakai di project lain:
+
+```python
+from javaxFlash import FlashClient
+
+client = FlashClient()
+response = client.flash("Buat ringkasan tentang REST API", mode="fast")
+
+if response.error:
+    raise RuntimeError(response.error)
+
+print(response.text)
+```

javaxflash-2.1.0/javaxFlash.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+javaxFlash/__init__.py
+javaxFlash/client.py
+javaxFlash/config.py
+javaxFlash/models.py
+javaxFlash/providers.py
+javaxFlash/router.py
+javaxFlash.egg-info/PKG-INFO
+javaxFlash.egg-info/SOURCES.txt
+javaxFlash.egg-info/dependency_links.txt
+javaxFlash.egg-info/requires.txt
+javaxFlash.egg-info/top_level.txt

javaxflash-2.1.0/javaxFlash.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

javaxflash-2.1.0/javaxFlash.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

javaxflash-2.1.0/javaxFlash.egg-info/top_level.txt

@@ -0,0 +1 @@
+javaxFlash

javaxflash-2.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "javaxFlash"
+version = "2.1.0"
+description = "Lightweight local-first AI router with javaxFlash and DeepSeek."
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "Javas Antony" }
+]
+requires-python = ">=3.10"
+dependencies = [
+  "requests>=2.31.0",
+]
+keywords = ["ai", "client", "router", "gemini", "deepseek"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.setuptools]
+packages = ["javaxFlash"]
+
+[tool.setuptools.package-data]
+
+[project.urls]
+"Homepage" = "https://pypi.org/project/javaxFlash/"

javaxflash-2.1.0/setup.cfg

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