instructor-ainative 0.1.0__tar.gz

instructor_ainative-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+# 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/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-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-0.1.0/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)