instructor-ainative 0.1.0__py3-none-any.whl

instructor_ainative/__init__.py

@@ -0,0 +1,30 @@
+"""
+instructor-ainative — Structured output extraction via AINative's free LLM API.
+
+Pre-configured instructor client that connects to AINative's OpenAI-compatible
+endpoint. Supports Llama, Qwen, and DeepSeek models with auto-provisioning.
+
+Usage:
+    from instructor_ainative import get_client
+    from pydantic import BaseModel
+
+    class User(BaseModel):
+        name: str
+        age: int
+
+    client = get_client()
+    user = client.chat.completions.create(
+        model="meta-llama/Llama-3.3-70B-Instruct",
+        response_model=User,
+        messages=[{"role": "user", "content": "Extract: John is 30"}],
+    )
+    print(user)  # User(name='John', age=30)
+
+Refs #3950
+"""
+
+from instructor_ainative.client import get_client, get_async_client
+from instructor_ainative.models import MODELS, get_model
+
+__all__ = ["get_client", "get_async_client", "MODELS", "get_model"]
+__version__ = "0.1.0"

instructor_ainative/client.py

@@ -0,0 +1,118 @@
+"""
+instructor-ainative — Client Factory
+
+Creates pre-configured instructor clients that connect to AINative's
+OpenAI-compatible API for structured output extraction.
+
+Refs #3950
+"""
+
+from typing import Optional
+
+import instructor
+from openai import OpenAI, AsyncOpenAI
+
+from instructor_ainative.provision import resolve_api_key
+
+BASE_URL = "https://api.ainative.studio/api/v1"
+
+
+def get_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    mode: instructor.Mode = instructor.Mode.JSON,
+    **kwargs,
+) -> instructor.Instructor:
+    """
+    Create a pre-configured instructor client for structured output extraction.
+
+    Uses AINative's free OpenAI-compatible API. If no API key is provided,
+    auto-provisions a free account.
+
+    Args:
+        api_key: Explicit API key. Falls back to env vars, credentials file,
+                 or auto-provisioning.
+        base_url: Override the API base URL. Defaults to AINative's endpoint.
+        mode: instructor mode for structured output. Defaults to JSON mode
+              which works best with open-source models.
+        **kwargs: Additional arguments passed to instructor.from_openai().
+
+    Returns:
+        An instructor-patched OpenAI client ready for structured output.
+
+    Example:
+        from instructor_ainative import get_client
+        from pydantic import BaseModel
+
+        class User(BaseModel):
+            name: str
+            age: int
+
+        client = get_client()
+        user = client.chat.completions.create(
+            model="meta-llama/Llama-3.3-70B-Instruct",
+            response_model=User,
+            messages=[{"role": "user", "content": "Extract: John is 30"}],
+        )
+    """
+    key = resolve_api_key(api_key)
+    base = base_url or BASE_URL
+
+    base_client = OpenAI(
+        api_key=key,
+        base_url=base,
+    )
+
+    return instructor.from_openai(base_client, mode=mode, **kwargs)
+
+
+def get_async_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    mode: instructor.Mode = instructor.Mode.JSON,
+    **kwargs,
+) -> instructor.AsyncInstructor:
+    """
+    Create a pre-configured async instructor client for structured output extraction.
+
+    Same as get_client() but uses AsyncOpenAI for async/await usage.
+
+    Args:
+        api_key: Explicit API key. Falls back to env vars, credentials file,
+                 or auto-provisioning.
+        base_url: Override the API base URL. Defaults to AINative's endpoint.
+        mode: instructor mode for structured output. Defaults to JSON mode.
+        **kwargs: Additional arguments passed to instructor.from_openai().
+
+    Returns:
+        An async instructor-patched OpenAI client.
+
+    Example:
+        import asyncio
+        from instructor_ainative import get_async_client
+        from pydantic import BaseModel
+
+        class User(BaseModel):
+            name: str
+            age: int
+
+        async def main():
+            client = get_async_client()
+            user = await client.chat.completions.create(
+                model="meta-llama/Llama-3.3-70B-Instruct",
+                response_model=User,
+                messages=[{"role": "user", "content": "Extract: John is 30"}],
+            )
+            print(user)
+
+        asyncio.run(main())
+    """
+    key = resolve_api_key(api_key)
+    base = base_url or BASE_URL
+
+    base_client = AsyncOpenAI(
+        api_key=key,
+        base_url=base,
+    )
+
+    return instructor.from_openai(base_client, mode=mode, **kwargs)

instructor_ainative/models.py

@@ -0,0 +1,55 @@
+"""
+instructor-ainative — Supported Models
+
+Model aliases and catalog for AINative's OpenAI-compatible endpoint.
+All models support structured output extraction via instructor.
+
+Refs #3950
+"""
+
+from typing import Optional
+
+# Model aliases -> full model identifiers
+MODELS = {
+    # Meta Llama
+    "llama": "meta-llama/Llama-3.3-70B-Instruct",
+    "llama-70b": "meta-llama/Llama-3.3-70B-Instruct",
+    "llama-8b": "meta-llama/Llama-3.1-8B-Instruct",
+    # Qwen
+    "qwen": "qwen3-coder-flash",
+    "qwen-coder": "qwen3-coder-flash",
+    # DeepSeek
+    "deepseek": "deepseek-4-flash",
+    "deepseek-flash": "deepseek-4-flash",
+    # Kimi
+    "kimi": "kimi-k2",
+}
+
+# Default model for get_client()
+DEFAULT_MODEL = "meta-llama/Llama-3.3-70B-Instruct"
+
+
+def get_model(alias: str) -> str:
+    """
+    Resolve a model alias to its full identifier.
+
+    Args:
+        alias: Short alias (e.g. "llama", "qwen") or full model ID.
+
+    Returns:
+        Full model identifier string.
+
+    Examples:
+        >>> get_model("llama")
+        'meta-llama/Llama-3.3-70B-Instruct'
+        >>> get_model("qwen")
+        'qwen3-coder-flash'
+        >>> get_model("meta-llama/Llama-3.3-70B-Instruct")
+        'meta-llama/Llama-3.3-70B-Instruct'
+    """
+    return MODELS.get(alias, alias)
+
+
+def list_models() -> dict:
+    """Return all available model aliases and their full identifiers."""
+    return dict(MODELS)

instructor_ainative/provision.py

@@ -0,0 +1,174 @@
+"""
+instructor-ainative — Auto-Provisioning
+
+Zero-friction provisioning for instructor users.
+On first use, if no API key is found, automatically provisions
+a free AINative account (72-hour TTL) that can be claimed later.
+
+Credential resolution order:
+1. Explicit api_key parameter
+2. AINATIVE_API_KEY environment variable
+3. ZERODB_API_KEY environment variable (shared with zerodb ecosystem)
+4. ~/.zerodb/credentials.json (shared credential store)
+5. Auto-provision via /api/v1/public/instant-db
+
+Refs #3950
+"""
+
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+ZERODB_DIR = Path.home() / ".zerodb"
+CREDS_PATH = ZERODB_DIR / "credentials.json"
+CONFIG_PATH = ZERODB_DIR / "config.json"
+CLOUD_API_URL = "https://api.ainative.studio"
+PROVISION_ENDPOINT = "/api/v1/public/instant-db"
+
+
+def resolve_api_key(explicit_key: Optional[str] = None) -> str:
+    """
+    Resolve an API key from all available sources.
+
+    Args:
+        explicit_key: Key passed directly by the user.
+
+    Returns:
+        A valid API key string.
+
+    Raises:
+        RuntimeError: If auto-provisioning fails and no key is available.
+    """
+    # 1. Explicit parameter
+    if explicit_key:
+        return explicit_key
+
+    # 2. Environment variables
+    env_key = (
+        os.environ.get("AINATIVE_API_KEY")
+        or os.environ.get("ZERODB_API_KEY")
+    )
+    if env_key:
+        return env_key
+
+    # 3. Credentials file (shared with zerodb ecosystem)
+    creds = _load_credentials()
+    if creds:
+        return creds
+
+    # 4. Auto-provision
+    return _auto_provision()
+
+
+def _load_credentials() -> Optional[str]:
+    """Load API key from ~/.zerodb/credentials.json."""
+    if CREDS_PATH.exists():
+        try:
+            data = json.loads(CREDS_PATH.read_text())
+            key = data.get("api_key")
+            if key:
+                return key
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    if CONFIG_PATH.exists():
+        try:
+            data = json.loads(CONFIG_PATH.read_text())
+            key = data.get("api_key") or data.get("cloud_api_key")
+            if key:
+                return key
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    return None
+
+
+def _auto_provision() -> str:
+    """
+    Auto-provision a free AINative account for structured output extraction.
+
+    Returns:
+        API key string.
+
+    Raises:
+        RuntimeError: If provisioning fails.
+    """
+    print(
+        "\n  No API key found — provisioning a free AINative account for structured outputs...",
+        file=sys.stderr,
+    )
+
+    try:
+        resp = requests.post(
+            f"{CLOUD_API_URL}{PROVISION_ENDPOINT}",
+            json={"agree_terms": True, "source": "instructor-ainative"},
+            timeout=15,
+        )
+
+        if resp.status_code == 429:
+            raise RuntimeError(
+                "Rate limited — too many provisions from this IP. "
+                "Sign up at https://ainative.studio/signup and set AINATIVE_API_KEY."
+            )
+
+        if resp.status_code not in (200, 201):
+            raise RuntimeError(
+                f"Provisioning failed (HTTP {resp.status_code}). "
+                "Sign up at https://ainative.studio/signup and set AINATIVE_API_KEY."
+            )
+
+        data = resp.json()
+        api_key = data.get("api_key", "")
+        if not api_key:
+            raise RuntimeError("Provisioning returned empty API key.")
+
+        _save_credentials(data)
+        _print_success(data)
+        return api_key
+
+    except requests.RequestException as exc:
+        raise RuntimeError(
+            f"Network error during provisioning: {exc}. "
+            "Set AINATIVE_API_KEY manually or sign up at https://ainative.studio/signup"
+        ) from exc
+
+
+def _save_credentials(data: dict) -> None:
+    """Save provisioned credentials to ~/.zerodb/ for ecosystem sharing."""
+    ZERODB_DIR.mkdir(parents=True, exist_ok=True)
+
+    creds = {
+        "api_key": data.get("api_key", ""),
+        "project_id": data.get("project_id", ""),
+        "base_url": data.get("base_url", CLOUD_API_URL),
+        "expires_at": data.get("expires_at", ""),
+        "claim_url": data.get("claim_url", ""),
+        "provisioned_at": datetime.now(tz=None).isoformat(),
+        "source": "instructor-ainative",
+    }
+
+    CREDS_PATH.write_text(json.dumps(creds, indent=2) + "\n")
+
+
+def _print_success(data: dict) -> None:
+    """Print success message with claim URL."""
+    expires = data.get("expires_at", "72 hours")
+    claim_url = data.get("claim_url", "https://ainative.studio/signup")
+    api_key = data.get("api_key", "")
+
+    print(
+        f"\n  Auto-provisioned! Free structured output API ready.\n"
+        f"\n"
+        f"  API Key:   {api_key[:12]}...\n"
+        f"  Expires:   {expires}\n"
+        f"  Saved to:  ~/.zerodb/credentials.json\n"
+        f"\n"
+        f"  To keep access permanently, claim your account:\n"
+        f"  {claim_url}\n",
+        file=sys.stderr,
+    )

instructor_ainative-0.1.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: instructor-ainative
+Version: 0.1.0
+Summary: Pre-configured instructor client for structured output extraction via AINative's free LLM API
+Author-email: AINative Studio <dev@ainative.studio>
+License: MIT
+Project-URL: Homepage, https://github.com/AINative-Studio/instructor-ainative
+Project-URL: Documentation, https://docs.ainative.studio/instructor
+Project-URL: Repository, https://github.com/AINative-Studio/instructor-ainative
+Project-URL: Issues, https://github.com/AINative-Studio/instructor-ainative/issues
+Keywords: instructor,instructor-plugin,structured-output,pydantic,json-extraction,free-llm,ainative,zerodb,openai-compatible,llama,qwen,deepseek,auto-provisioning,claude,cursor,function-calling,schema-extraction,data-extraction,llm-structured,json-mode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: instructor>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# instructor-ainative
+
+Pre-configured [instructor](https://github.com/jxnl/instructor) client for structured output extraction using AINative's free LLM API.
+
+**Zero setup.** Works with Llama 3.3 70B, Qwen3, DeepSeek 4, and Kimi K2 — all free.
+
+## Install
+
+```bash
+pip install instructor-ainative
+```
+
+## Quick Start
+
+```python
+from instructor_ainative import get_client
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+client = get_client()  # Auto-provisions free API key
+user = client.chat.completions.create(
+    model="meta-llama/Llama-3.3-70B-Instruct",
+    response_model=User,
+    messages=[{"role": "user", "content": "Extract: John is 30"}],
+)
+print(user)  # User(name='John', age=30)
+```
+
+## How It Works
+
+`instructor-ainative` wraps [instructor](https://python.useinstructor.com/) with a pre-configured OpenAI client pointing at AINative's free, OpenAI-compatible API. You get structured Pydantic output extraction from open-source models without any API key setup.
+
+On first use, the package auto-provisions a free API key (72-hour TTL). Claim your account at [ainative.studio/signup](https://ainative.studio/signup) for permanent access.
+
+## Available Models
+
+Use aliases or full model IDs:
+
+```python
+from instructor_ainative import get_model, MODELS
+
+# Aliases
+get_model("llama")     # meta-llama/Llama-3.3-70B-Instruct
+get_model("qwen")      # qwen3-coder-flash
+get_model("deepseek")  # deepseek-4-flash
+get_model("kimi")      # kimi-k2
+```
+
+## Async Support
+
+```python
+import asyncio
+from instructor_ainative import get_async_client
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+async def main():
+    client = get_async_client()
+    user = await client.chat.completions.create(
+        model="meta-llama/Llama-3.3-70B-Instruct",
+        response_model=User,
+        messages=[{"role": "user", "content": "Extract: John is 30"}],
+    )
+    print(user)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### API Key Resolution Order
+
+1. Explicit `api_key` parameter
+2. `AINATIVE_API_KEY` environment variable
+3. `ZERODB_API_KEY` environment variable
+4. `~/.zerodb/credentials.json` (shared with ZeroDB ecosystem)
+5. Auto-provision (free, 72-hour TTL)
+
+### Bring Your Own Key
+
+```bash
+export AINATIVE_API_KEY=your-key-here
+```
+
+```python
+# Or pass directly
+client = get_client(api_key="your-key-here")
+```
+
+### Custom Base URL
+
+```python
+client = get_client(base_url="https://your-proxy.example.com/v1")
+```
+
+### Instructor Mode
+
+```python
+import instructor
+client = get_client(mode=instructor.Mode.TOOLS)  # Default is JSON mode
+```
+
+## Complex Extraction
+
+```python
+from instructor_ainative import get_client
+from pydantic import BaseModel, Field
+from typing import List
+
+class Address(BaseModel):
+    street: str
+    city: str
+    state: str
+    zip_code: str = Field(description="5-digit ZIP code")
+
+class Contact(BaseModel):
+    name: str
+    email: str
+    phone: str
+    addresses: List[Address]
+
+client = get_client()
+contact = client.chat.completions.create(
+    model="meta-llama/Llama-3.3-70B-Instruct",
+    response_model=Contact,
+    messages=[{
+        "role": "user",
+        "content": """
+        Extract contact info: Jane Smith, jane@example.com, 555-0123.
+        Lives at 123 Main St, Austin TX 78701 and
+        456 Oak Ave, Denver CO 80202.
+        """
+    }],
+)
+```
+
+## Why instructor-ainative?
+
+| Feature | instructor + OpenAI | instructor-ainative |
+|---------|-------------------|-------------------|
+| Setup | Get API key, set env var | `pip install` and go |
+| Cost | Pay per token | Free |
+| Models | GPT-4o, etc. | Llama 70B, Qwen, DeepSeek |
+| Structured output | Yes | Yes |
+| Auto-provisioning | No | Yes |
+
+## License
+
+MIT

instructor_ainative-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+instructor_ainative/__init__.py,sha256=pqAVIQ_TuZrjkA50XFgSZFN2PKgP9nPmn3Sbuf7YOLY,900
+instructor_ainative/client.py,sha256=aAV_eaNT9yjhSrXXDFGhA0KBp1Ywg_U7p-oiU_myWpg,3487
+instructor_ainative/models.py,sha256=nmFSZSXfH5cd157pJVJp9RKCtXgZYpn2-VJ3MvH14KA,1395
+instructor_ainative/provision.py,sha256=IEFBECQLAWvL8W2gyAQlvQyho6MMS_z0MuJL2ki5dhs,5033
+instructor_ainative-0.1.0.dist-info/licenses/LICENSE,sha256=-3M2h1U80S6mPyiuvRG25A0l1xZGpa7eO43lysBIzBY,1072
+instructor_ainative-0.1.0.dist-info/METADATA,sha256=soP4c5jCSqinvCickbLIbF2G89jvwkNllntKaekmgJI,5473
+instructor_ainative-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+instructor_ainative-0.1.0.dist-info/top_level.txt,sha256=oUoo5v8osWDBUpBhmdPON63zWVdZYnPhIDLgG84gkik,20
+instructor_ainative-0.1.0.dist-info/RECORD,,

instructor_ainative-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

instructor_ainative-0.1.0.dist-info/licenses/LICENSE

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

instructor_ainative-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+instructor_ainative