afsar 1.0__py3-none-any.whl

afsar/__init__.py

@@ -0,0 +1,27 @@
+"""afsar - Simple students' API to LLMs."""
+
+from afsar.core import ask, get_active_adapter, reset, setup
+from afsar.exceptions import (
+    AfsarError,
+    AuthenticationError,
+    ExecutionError,
+    ModelNotFoundError,
+    NotSetupError,
+    UnsupportedFeatureError,
+)
+
+__version__ = "1.0"
+
+__all__ = [
+    "setup",
+    "ask",
+    "reset",
+    "get_active_adapter",
+    "AfsarError",
+    "NotSetupError",
+    "ModelNotFoundError",
+    "UnsupportedFeatureError",
+    "ExecutionError",
+    "AuthenticationError",
+    "__version__",
+]

afsar/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Adapters package for afsar."""
+
+from afsar.adapters.agy import AgyAdapter
+from afsar.adapters.base import BaseAdapter
+from afsar.adapters.claude import ClaudeAdapter
+from afsar.adapters.gemini import GeminiAdapter
+from afsar.adapters.openai import OpenAIAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "ClaudeAdapter",
+    "AgyAdapter",
+    "GeminiAdapter",
+    "OpenAIAdapter",
+]

afsar/adapters/agy.py

@@ -0,0 +1,87 @@
+"""Antigravity (agy) CLI subprocess adapter."""
+
+import json
+import subprocess
+from typing import Any
+
+from afsar.adapters.base import BaseAdapter
+from afsar.exceptions import ExecutionError
+from afsar.schema import _strip_markdown_fence, to_json_schema, validate_schema_output
+
+
+class AgyAdapter(BaseAdapter):
+    """Adapter for local Antigravity (agy) CLI."""
+
+    name = "agy"
+    supports_tools = True
+    supports_thinking = True
+    supports_schema = True
+
+    def __init__(self, model: str | None = None, tools: list[str] | None = None) -> None:
+        self.model = model
+        self.tools = tools if tools is not None else ["python", "files"]
+
+    def _build_cmd(
+        self,
+        prompt: str,
+        format: str,
+        schema: Any,
+        thinking: bool | None,
+    ) -> list[str]:
+        cmd = ["agy", "-p", prompt, "--output-format", "json", "--dangerously-skip-permissions"]
+        if self.model:
+            cmd.extend(["--model", self.model])
+
+        if schema is not None:
+            cmd.extend(["--json-schema", json.dumps(to_json_schema(schema))])
+        elif format == "json":
+            cmd.extend(["--json-schema", json.dumps({"type": "object"})])
+
+        if thinking is not None:
+            cmd.extend(["--effort", "high" if thinking else "low"])
+
+        return cmd
+
+    def _parse_output(self, stdout: str) -> str:
+        try:
+            data = json.loads(stdout)
+            if data.get("status") not in (None, "SUCCESS"):
+                raise ExecutionError(f"agy error: {stdout}")
+            if "structured_output" in data and data["structured_output"] is not None:
+                return json.dumps(data["structured_output"])
+            return str(data.get("response", ""))
+        except json.JSONDecodeError:
+            return stdout.strip()
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        format: str = "text",
+        schema: Any = None,
+        temperature: float | None = None,
+        thinking: bool | None = None,
+    ) -> Any:
+        cmd = self._build_cmd(prompt, format, schema, thinking)
+
+        try:
+            res = subprocess.run(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except Exception as e:
+            raise ExecutionError(f"Failed to execute agy CLI: {e}") from e
+
+        if res.returncode != 0 and not res.stdout:
+            raise ExecutionError(f"agy CLI exited with code {res.returncode}: {res.stderr.strip()}")
+
+        result_str = self._parse_output(res.stdout)
+        if schema is not None:
+            return validate_schema_output(schema, result_str)
+        if format == "json":
+            return _strip_markdown_fence(result_str)
+
+        return result_str

afsar/adapters/base.py

@@ -0,0 +1,25 @@
+"""Base adapter interface for LLM models and local agents."""
+
+import abc
+from typing import Any
+
+
+class BaseAdapter(abc.ABC):
+    """Abstract base class for all model adapters."""
+
+    name: str = "base"
+    supports_tools: bool = False
+    supports_thinking: bool = False
+    supports_schema: bool = False
+
+    @abc.abstractmethod
+    def ask(
+        self,
+        prompt: str,
+        *,
+        format: str = "text",
+        schema: Any = None,
+        temperature: float | None = None,
+        thinking: bool | None = None,
+    ) -> Any:
+        """Execute a prompt against the model and return the result."""

afsar/adapters/claude.py

@@ -0,0 +1,103 @@
+"""Claude Code CLI subprocess adapter."""
+
+import json
+import subprocess
+from typing import Any
+
+from afsar.adapters.base import BaseAdapter
+from afsar.exceptions import AuthenticationError, ExecutionError
+from afsar.schema import _strip_markdown_fence, to_json_schema, validate_schema_output
+
+
+class ClaudeAdapter(BaseAdapter):
+    """Adapter for local Claude Code CLI."""
+
+    name = "claude"
+    supports_tools = True
+    supports_thinking = True
+    supports_schema = True
+
+    def __init__(self, model: str | None = None, tools: list[str] | None = None) -> None:
+        self.model = model
+        self.tools = tools if tools is not None else ["python", "files"]
+
+    def _build_cmd(
+        self,
+        prompt: str,
+        format: str,
+        schema: Any,
+        thinking: bool | None,
+    ) -> list[str]:
+        cmd = ["claude", "-p", prompt, "--output-format", "json", "--dangerously-skip-permissions"]
+        if self.model:
+            cmd.extend(["--model", self.model])
+
+        tools_arg = "default" if self.tools else ""
+        cmd.extend(["--tools", tools_arg])
+
+        if schema is not None:
+            cmd.extend(["--json-schema", json.dumps(to_json_schema(schema))])
+        elif format == "json":
+            cmd.extend(["--json-schema", json.dumps({"type": "object"})])
+
+        if thinking is not None:
+            cmd.extend(["--effort", "high" if thinking else "low"])
+
+        return cmd
+
+    def _parse_output(self, stdout: str) -> str:
+        try:
+            data = json.loads(stdout)
+            if data.get("is_error"):
+                err_msg = str(data.get("result", stdout))
+                if (
+                    data.get("api_error_status") == 401
+                    or "authentication" in err_msg.lower()
+                    or "oauth" in err_msg.lower()
+                ):
+                    raise AuthenticationError(
+                        "Claude authentication failed (OAuth access token is invalid or expired).\n"
+                        "Please run 'claude auth login' in your terminal to re-authenticate, "
+                        "or switch provider using: afsar.setup(provider='agy')"
+                    )
+                raise ExecutionError(f"Claude error: {err_msg}")
+            if "structured_output" in data and data["structured_output"] is not None:
+                return json.dumps(data["structured_output"])
+            return str(data.get("result", ""))
+        except json.JSONDecodeError:
+            return stdout.strip()
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        format: str = "text",
+        schema: Any = None,
+        temperature: float | None = None,
+        thinking: bool | None = None,
+    ) -> Any:
+        cmd = self._build_cmd(prompt, format, schema, thinking)
+
+        try:
+            res = subprocess.run(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except Exception as e:
+            raise ExecutionError(f"Failed to execute claude CLI: {e}") from e
+
+        if res.returncode != 0 and not res.stdout:
+            raise ExecutionError(
+                f"Claude CLI exited with code {res.returncode}: {res.stderr.strip()}"
+            )
+
+        result_str = self._parse_output(res.stdout)
+        if schema is not None:
+            return validate_schema_output(schema, result_str)
+        if format == "json":
+            return _strip_markdown_fence(result_str)
+
+        return result_str

afsar/adapters/gemini.py

@@ -0,0 +1,86 @@
+"""Google Gemini REST API adapter using standard library urllib."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from afsar.adapters.base import BaseAdapter
+from afsar.exceptions import ExecutionError
+from afsar.schema import _strip_markdown_fence, to_json_schema, validate_schema_output
+
+
+class GeminiAdapter(BaseAdapter):
+    """Adapter for Google Gemini REST API."""
+
+    name = "gemini"
+    supports_tools = False
+    supports_thinking = True
+    supports_schema = True
+
+    def __init__(self, model: str | None = None, api_key: str | None = None) -> None:
+        self.model = model or "gemini-2.0-flash"
+        self.api_key = api_key or os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            raise ValueError("Gemini API key is required. Set GEMINI_API_KEY or pass api_key.")
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        format: str = "text",
+        schema: Any = None,
+        temperature: float | None = None,
+        thinking: bool | None = None,
+    ) -> Any:
+        url = (
+            f"https://generativelanguage.googleapis.com/v1beta/models/{self.model}:generateContent"
+            f"?key={self.api_key}"
+        )
+
+        gen_config: dict[str, Any] = {}
+        if temperature is not None:
+            gen_config["temperature"] = temperature
+
+        if schema is not None:
+            gen_config["responseMimeType"] = "application/json"
+            gen_config["responseSchema"] = to_json_schema(schema)
+        elif format == "json":
+            gen_config["responseMimeType"] = "application/json"
+
+        payload: dict[str, Any] = {
+            "contents": [{"parts": [{"text": prompt}]}],
+        }
+        if gen_config:
+            payload["generationConfig"] = gen_config
+
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8", errors="replace")
+            raise ExecutionError(f"Gemini API error ({e.code}): {error_body}") from e
+        except Exception as e:
+            raise ExecutionError(f"Failed to communicate with Gemini API: {e}") from e
+
+        try:
+            candidates = data.get("candidates", [])
+            parts = candidates[0].get("content", {}).get("parts", [])
+            result_str = parts[0].get("text", "")
+        except (IndexError, KeyError) as e:
+            raise ExecutionError(f"Unexpected response structure from Gemini API: {data}") from e
+
+        if schema is not None:
+            return validate_schema_output(schema, result_str)
+        if format == "json":
+            return _strip_markdown_fence(result_str)
+
+        return result_str

afsar/adapters/openai.py

@@ -0,0 +1,89 @@
+"""OpenAI REST API adapter using standard library urllib."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from afsar.adapters.base import BaseAdapter
+from afsar.exceptions import ExecutionError
+from afsar.schema import _strip_markdown_fence, to_json_schema, validate_schema_output
+
+
+class OpenAIAdapter(BaseAdapter):
+    """Adapter for OpenAI Chat Completions REST API."""
+
+    name = "openai"
+    supports_tools = False
+    supports_thinking = True
+    supports_schema = True
+
+    def __init__(self, model: str | None = None, api_key: str | None = None) -> None:
+        self.model = model or "gpt-4o-mini"
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError("OpenAI API key is required. Set OPENAI_API_KEY or pass api_key.")
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        format: str = "text",
+        schema: Any = None,
+        temperature: float | None = None,
+        thinking: bool | None = None,
+    ) -> Any:
+        url = "https://api.openai.com/v1/chat/completions"
+
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if temperature is not None:
+            payload["temperature"] = temperature
+
+        if schema is not None:
+            schema_dict = to_json_schema(schema)
+            payload["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": getattr(schema, "__name__", "ResponseSchema"),
+                    "strict": False,
+                    "schema": schema_dict,
+                },
+            }
+        elif format == "json":
+            payload["response_format"] = {"type": "json_object"}
+
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8", errors="replace")
+            raise ExecutionError(f"OpenAI API error ({e.code}): {error_body}") from e
+        except Exception as e:
+            raise ExecutionError(f"Failed to communicate with OpenAI API: {e}") from e
+
+        try:
+            choices = data.get("choices", [])
+            result_str = choices[0].get("message", {}).get("content", "")
+        except (IndexError, KeyError) as e:
+            raise ExecutionError(f"Unexpected response structure from OpenAI API: {data}") from e
+
+        if schema is not None:
+            return validate_schema_output(schema, result_str)
+        if format == "json":
+            return _strip_markdown_fence(result_str)
+
+        return result_str

afsar/core.py

@@ -0,0 +1,164 @@
+"""Core session management and procedural API for afsar."""
+
+import os
+import shutil
+from collections.abc import Sequence
+from typing import Any
+
+from afsar.adapters.base import BaseAdapter
+from afsar.exceptions import (
+    ModelNotFoundError,
+    NotSetupError,
+    UnsupportedFeatureError,
+)
+
+_active_adapter: BaseAdapter | None = None
+
+
+def get_active_adapter() -> BaseAdapter | None:
+    """Return the currently configured adapter, or None if not setup."""
+    return _active_adapter
+
+
+def reset() -> None:
+    """Reset the global afsar session state. Useful for tests."""
+    global _active_adapter
+    _active_adapter = None
+
+
+def _normalize_explicit_provider(provider: str) -> str:
+    """Normalize and validate an explicitly provided provider string."""
+    normalized = provider.strip().lower()
+    alias_map = {
+        "claude": "claude",
+        "claude-code": "claude",
+        "agy": "agy",
+        "antigravity": "agy",
+        "gemini": "gemini",
+        "openai": "openai",
+    }
+    if normalized not in alias_map:
+        raise ValueError(
+            f"Unknown provider '{provider}'. Supported: 'claude', 'agy', 'gemini', 'openai'."
+        )
+    return alias_map[normalized]
+
+
+def _find_candidate_providers(api_key: str | None = None) -> list[str]:
+    """Auto-detect available providers according to priority."""
+    candidates: list[str] = []
+    if shutil.which("claude") is not None:
+        candidates.append("claude")
+    if shutil.which("agy") is not None:
+        candidates.append("agy")
+    if api_key or os.getenv("GEMINI_API_KEY"):
+        candidates.append("gemini")
+    if api_key or os.getenv("OPENAI_API_KEY"):
+        candidates.append("openai")
+    return candidates
+
+
+def detect_providers(
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+) -> list[str]:
+    """Detect candidate providers based on explicit overrides, env vars, or auto-detection."""
+    chosen = provider or os.getenv("AFSAR_PROVIDER")
+    if chosen is not None:
+        return [_normalize_explicit_provider(chosen)]
+
+    candidates = _find_candidate_providers(api_key=api_key)
+    if not candidates:
+        raise ModelNotFoundError(
+            "No local agent (claude-code, agy) or remote API keys (GEMINI_API_KEY, OPENAI_API_KEY) found."
+        )
+    return candidates
+
+
+def detect_provider(
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+) -> str:
+    """Detect the first provider based on explicit overrides or auto-detection."""
+    return detect_providers(provider=provider, api_key=api_key)[0]
+
+
+def _create_adapter(
+    provider: str,
+    model: str | None,
+    api_key: str | None,
+    tools: Sequence[str] | None,
+) -> BaseAdapter:
+    """Instantiate the corresponding adapter instance for a provider."""
+    tool_list = list(tools) if tools else []
+    if provider == "claude":
+        from afsar.adapters.claude import ClaudeAdapter
+
+        return ClaudeAdapter(model=model, tools=tool_list)
+    if provider == "agy":
+        from afsar.adapters.agy import AgyAdapter
+
+        return AgyAdapter(model=model, tools=tool_list)
+    if provider == "gemini":
+        from afsar.adapters.gemini import GeminiAdapter
+
+        return GeminiAdapter(model=model, api_key=api_key)
+    if provider == "openai":
+        from afsar.adapters.openai import OpenAIAdapter
+
+        return OpenAIAdapter(model=model, api_key=api_key)
+
+    raise ModelNotFoundError(f"Unsupported provider '{provider}'.")
+
+
+def setup(
+    model: str | None = None,
+    api_key: str | None = None,
+    tools: Sequence[str] | None = ("python", "files"),
+    provider: str | None = None,
+) -> None:
+    """Configure the active LLM provider and tool settings."""
+    global _active_adapter
+
+    detected = detect_provider(provider=provider, api_key=api_key)
+
+    if bool(tools) and detected not in {"claude", "agy"}:
+        raise UnsupportedFeatureError(
+            f"Remote models ({detected}) do not support local code execution or file tools yet.\n"
+            f"To use remote models, explicitly initialize with: afsar.setup(tools=[])"
+        )
+
+    _active_adapter = _create_adapter(detected, model, api_key, tools)
+
+
+def ask(
+    prompt: str,
+    *,
+    format: str = "text",
+    schema: Any = None,
+    temperature: float | None = None,
+    thinking: bool | None = None,
+) -> Any:
+    """Send a prompt to the configured LLM and return the answer."""
+    if _active_adapter is None:
+        raise NotSetupError(
+            "afsar is not configured. Please call afsar.setup() before afsar.ask()."
+        )
+
+    if format not in {"text", "json"}:
+        raise ValueError(f"Invalid format '{format}'. Supported formats: 'text', 'json'.")
+
+    if thinking is True and not _active_adapter.supports_thinking:
+        raise ValueError(
+            f"Thinking mode requested, but adapter '{_active_adapter.name}' does not support thinking."
+        )
+
+    return _active_adapter.ask(
+        prompt,
+        format=format,
+        schema=schema,
+        temperature=temperature,
+        thinking=thinking,
+    )

afsar/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exception hierarchy for afsar."""
+
+
+class AfsarError(Exception):
+    """Base exception for all afsar errors."""
+
+
+class NotSetupError(AfsarError):
+    """Raised when afsar.ask() is called before afsar.setup()."""
+
+
+class ModelNotFoundError(AfsarError):
+    """Raised when no local agent or remote API key can be found."""
+
+
+class UnsupportedFeatureError(AfsarError):
+    """Raised when a requested feature or tool is unsupported by the selected model."""
+
+
+class ExecutionError(AfsarError):
+    """Raised when an underlying agent execution fails."""
+
+
+class AuthenticationError(ExecutionError):
+    """Raised when an underlying agent fails due to missing or invalid authentication."""

afsar/schema.py

@@ -0,0 +1,111 @@
+"""Schema extraction and validation helpers without mandatory dependencies."""
+
+import dataclasses
+import json
+from collections.abc import Sequence
+from typing import Any, cast, get_type_hints
+
+
+def is_pydantic_model(cls: Any) -> bool:
+    """Check if cls is a Pydantic model class without importing pydantic at module load."""
+    return isinstance(cls, type) and (
+        hasattr(cls, "model_json_schema") or hasattr(cls, "parse_raw")
+    )
+
+
+def _infer_type_string(field_type: Any) -> str:
+    """Map a Python type to a JSON schema type string."""
+    if field_type in (int, float):
+        return "number" if field_type is float else "integer"
+    if field_type is bool:
+        return "boolean"
+    if getattr(field_type, "__origin__", None) in (list, Sequence):
+        return "array"
+    return "string"
+
+
+def _dataclass_to_json_schema(schema_cls: Any) -> dict[str, Any]:
+    """Convert a dataclass to a JSON schema dict."""
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    try:
+        type_hints = get_type_hints(schema_cls)
+    except Exception:
+        type_hints = {}
+
+    for f in dataclasses.fields(schema_cls):
+        field_type = type_hints.get(f.name, f.type)
+        properties[f.name] = {"type": _infer_type_string(field_type)}
+        if f.default is dataclasses.MISSING and f.default_factory is dataclasses.MISSING:
+            required.append(f.name)
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+
+
+def to_json_schema(schema_cls: Any) -> dict[str, Any]:
+    """Convert a schema class (Pydantic, dataclass, or dict) to a standard JSON schema dict."""
+    if isinstance(schema_cls, dict):
+        return schema_cls
+
+    if is_pydantic_model(schema_cls):
+        if hasattr(schema_cls, "model_json_schema"):
+            return cast(dict[str, Any], schema_cls.model_json_schema())
+        if hasattr(schema_cls, "schema"):
+            return cast(dict[str, Any], schema_cls.schema())
+
+    if dataclasses.is_dataclass(schema_cls):
+        return _dataclass_to_json_schema(schema_cls)
+
+    raise TypeError(
+        f"Unsupported schema type '{schema_cls}'. Pass a Pydantic model, @dataclass, or JSON schema dict."
+    )
+
+
+def _strip_markdown_fence(raw_text: str) -> str:
+    """Strip markdown code fence blocks (```json ... ```) if present."""
+    cleaned = raw_text.strip()
+    if "```json" in cleaned:
+        cleaned = cleaned.split("```json", 1)[1].split("```", 1)[0].strip()
+    elif "```" in cleaned:
+        cleaned = cleaned.split("```", 1)[1].split("```", 1)[0].strip()
+
+    try:
+        json.loads(cleaned)
+        return cleaned
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start != -1 and end > start:
+            candidate = cleaned[start : end + 1]
+            try:
+                json.loads(candidate)
+                return candidate
+            except json.JSONDecodeError:
+                pass
+    return cleaned
+
+
+def validate_schema_output(schema_cls: Any, raw_json_str: str) -> Any:
+    """Validate and instantiate the target schema class from a raw JSON string."""
+    cleaned = _strip_markdown_fence(raw_json_str)
+
+    if is_pydantic_model(schema_cls):
+        if hasattr(schema_cls, "model_validate_json"):
+            return schema_cls.model_validate_json(cleaned)
+        if hasattr(schema_cls, "parse_raw"):
+            return schema_cls.parse_raw(cleaned)
+
+    parsed = json.loads(cleaned)
+    if dataclasses.is_dataclass(schema_cls):
+        cls_factory = cast(Any, schema_cls)
+        if isinstance(parsed, dict):
+            field_names = {f.name for f in dataclasses.fields(schema_cls)}
+            filtered = {k: v for k, v in parsed.items() if k in field_names}
+            return cls_factory(**filtered)
+        return cls_factory(**parsed)
+
+    return parsed

afsar-1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: afsar
+Version: 1.0
+Summary: LLM API library for students utilizing local agents or remote APIs
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.17.0; extra == 'dev'
+Requires-Dist: xenon>=0.9.0; extra == 'dev'
+Provides-Extra: schema
+Requires-Dist: pydantic>=2.0.0; extra == 'schema'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="src/afsar/resources/afsar.png" alt="afsar logo" width="180" />
+</p>
+
+# afsar
+
+A simple, student-friendly procedural Python library providing a uniform interface to LLMs. `afsar` prioritizes installed local coding agents (`claude-code`, `antigravity`) so students can use their existing agents and tools, and smoothly falls back to remote cloud APIs (`Gemini`, `OpenAI`).
+
+---
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install afsar
+```
+
+---
+
+## Quickstart
+
+### 1. Basic Text Query
+
+```python
+import afsar
+
+# Setup is explicit and required once before asking
+afsar.setup()
+
+answer = afsar.ask("How do you define a function in Python?")
+print(answer)
+```
+
+### 2. Structured Output with `@dataclass`
+
+You don't need Pydantic to get typed objects. Standard Python dataclasses work out of the box:
+
+```python
+from dataclasses import dataclass
+import afsar
+
+
+@dataclass
+class QuizQuestion:
+    question: str
+    points: int
+    topic: str
+
+
+afsar.setup()
+quiz = afsar.ask("Create a beginner Python question.", schema=QuizQuestion)
+
+print(quiz.question)
+print(f"Points: {quiz.points}")
+print(f"Topic: {quiz.topic}")
+```
+
+### 3. Raw JSON Output
+
+If you just want a JSON-formatted string:
+
+```python
+import afsar
+
+afsar.setup()
+raw_json = afsar.ask("List 3 Python data structures.", format="json")
+print(raw_json)  # Returns clean JSON string
+```
+
+### 4. Student Coding Exercises (Local Tools)
+
+When using local agents (`claude` or `agy`), `afsar` defaults to `tools=["python", "files"]`. This allows asking the agent to write and test code locally:
+
+```python
+import afsar
+
+afsar.setup()
+response = afsar.ask(
+    "Write a solution to check if a word is a palindrome, save it to palindrome.py, run it with python, and show the result."
+)
+print(response)
+```
+
+---
+
+## Remote APIs (Gemini & OpenAI)
+
+Remote models do not support local file or execution tools. When connecting to remote APIs, explicitly pass `tools=[]`:
+
+```python
+import afsar
+
+# Using Gemini
+afsar.setup(provider="gemini", api_key="YOUR_GEMINI_KEY", tools=[])
+
+# Or using OpenAI
+afsar.setup(provider="openai", api_key="YOUR_OPENAI_KEY", tools=[])
+
+answer = afsar.ask("Explain recursion in simple terms.")
+print(answer)
+```
+
+---
+
+## Auto-Detection & Priority
+
+Calling `afsar.setup()` without arguments automatically searches for available providers in this order:
+
+1. **Claude Code CLI** (`claude`) in `PATH`
+2. **Antigravity CLI** (`agy`) in `PATH`
+3. **Google Gemini** (`GEMINI_API_KEY` in environment)
+4. **OpenAI** (`OPENAI_API_KEY` in environment)
+
+You can override the provider explicitly in code:
+
+```python
+afsar.setup(provider="agy")
+```
+
+Or via the `AFSAR_PROVIDER` environment variable:
+
+```bash
+export AFSAR_PROVIDER=agy
+```
+
+---
+
+## Exceptions
+
+- `NotSetupError`: Raised if `afsar.ask()` is called before `afsar.setup()`.
+- `UnsupportedFeatureError`: Raised if requesting local tools (`tools=["python", "files"]`) on remote API providers.
+- `ModelNotFoundError`: Raised if no supported local CLI or remote API key is discovered.
+- `ExecutionError`: Raised if a CLI command or remote API request fails.

afsar-1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+afsar/__init__.py,sha256=vF9I9mmYi85I7WxQn8PuTO3ROivRWnnYYyb9qWqS5SU,535
+afsar/core.py,sha256=0shFUDzqg7rHgGi5-EIR-jcE8nRlH_VxCJT7qMTVLCY,5046
+afsar/exceptions.py,sha256=TNtpkYc-Q_g1O95TM8KI9iaW-Br6NMTeBjmtmoYFGg0,695
+afsar/schema.py,sha256=NwykFkX_zyhSLxrPyRtBhm73JR3RfWNg5c39e0MxIxQ,3864
+afsar/adapters/__init__.py,sha256=_W4xYYSYTfCmTIN2Nq7vhS72ffwBfc1yFqjJRuHRjPU,380
+afsar/adapters/agy.py,sha256=2HboL_Bz0T9nHo-ZkuSH_3SXo-smtAfdVwX6v7204cY,2804
+afsar/adapters/base.py,sha256=fSfvb1X7X5QHN8GMdudY_r2cEKzF8WtEC2MDTTU8nZc,616
+afsar/adapters/claude.py,sha256=8fsmG9KCSdAa0W5v0Av2P58wRBFKwaEZcAOVrZXpbf8,3541
+afsar/adapters/gemini.py,sha256=Flzxp1qniYvRQOls4aLyE6XDJhQlGJyA-M53016Lyg4,2963
+afsar/adapters/openai.py,sha256=kyud17lkVcloPisIcShrwzg5DOAbKgFTqvMFFbpQqrk,3039
+afsar/resources/afsar.png,sha256=VMJvk2p-0zA2zGvc_5IAi5Vz64EWEZrRJEioBpbTplM,25240
+afsar-1.0.dist-info/METADATA,sha256=BIX2jPoYGwhiNqCb5V1QWB3KfArPJWQXhNfdkYJHSPM,3615
+afsar-1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+afsar-1.0.dist-info/RECORD,,

afsar-1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any