Metadata-Version: 2.4
Name: ixentbench
Version: 1.0.14
Summary: The AI benchmark beyond memorization — Causal spatial reasoning at 4×10⁸⁵ scale
Author-email: "iXentLabs (iXent Games SL)" <contact@ixentlabs.com>
License: iXentBench™ NON-COMMERCIAL SOURCE LICENSE
        
        Copyright (c) 2026 iXentLabs / Antoni Guasch / María Isabel Valdez (iXent Games SL). 
        All rights reserved.
        
        This software and associated documentation files (the "Software") are copyrighted material. The intellectual property rights of the mechanics, design, name, and concept derived from the original physical board game and digital applications belong exclusively to the authors.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this Software, to deal in the Software without restriction solely for academic research, educational, and non-commercial personal purposes, including the rights to use, copy, modify, and merge copies of the Software, 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.
        
        COMMERCIAL RESTRICTION: The Software may not be used, in whole or in part, for any Commercial Purpose by any corporation, business entity, organization, or private individual. "Commercial Purpose" includes, without limitation:
        
        a) Selling, licensing, or renting the Software.
        b) Providing the Software as a service (SaaS) to third parties in exchange for financial compensation.
        c) Using the Software to evaluate, train, or benchmark Artificial Intelligence models that serve an ultimate commercial or corporate purpose.
        d) Integrating the Software into a larger commercial product or service.
        
        Any commercial use requires a separate, written license agreement ("Commercial License") explicitly granted by the copyright holders.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY.
        
        
Project-URL: Homepage, https://ixentlabs.com
Project-URL: Repository, https://github.com/ixentlabs/ixentbench
Project-URL: Documentation, https://github.com/ixentlabs/ixentbench#readme
Keywords: ai,benchmark,reasoning,llm,evaluation
Classifier: License :: Other/Proprietary License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0
Requires-Dist: google-genai>=1.0
Requires-Dist: google-auth>=2.28
Requires-Dist: google-auth-oauthlib>=1.2
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Dynamic: license-file

# iXentBench™ — The AI Benchmark Beyond Memorization

Causal spatial reasoning at 4×10⁸⁵ scale, powered by **Caps i Caps©** — the game that makes memorization impossible. 
Developed by [iXentLabs](https://ixentlabs.com) (iXent Games S.L.)

---
## Installation & Setup

**1. Install the engine:**

```bash
pip install ixentbench
```

---

**2. Initialize your local folder**

```bash
ixentbench
```
You will see this welcome message confirming your folder is ready:

```bash
=======================================================
  ✅ iXentBench installed successfully!
=======================================================

  📁 Player folder:  /Users/your-user/ixentbench
  📖 Manual:         double-click README.html
  🔑 API Key setup:  double-click env_configuration.html
  📄 Config file:    .env  (add your API Key here)

  Next steps:
  1. Open your player folder:
     /Users/your-user/ixentbench
  2. Double-click env_configuration.html
  3. Follow the instructions to add your API Key
  4. Run from ANY folder:  ixentbench login
  5. Go to ixentlabs.com to create your session
  6. Run from ANY folder: ixentbench play --session YOUR_SESSION_ID

  iXentLabs never accesses your keys or this folder.
=======================================================
```

---

## Quick Start

**1. Configure your session** at [ixentlabs.com](https://ixentlabs.com)  
Login with Google, select benchmark type, level and AI model.  
Download your `.env` file and add your API Key.

**2. Run your session:**

```bash
ixentbench play --session YOUR_SESSION_ID
```

The visualizer opens automatically in your browser.

---

## Play Modes

There are four ways to play iXentBench, designed for every type of participant — from AI engineers to pure mathematicians and AI enthusiasts.

| Flag | A — BYOK | B — Local Model | C — Custom Agent | D — Sponsored |
|---|---|---|---|---|
| Uses LLM | ✅ Cloud API | ✅ Local | ❌ Pure code | ✅ iXentLabs |
| API Key needed | ✅ Yours | ❌ No | ❌ No | ❌ No |
| `--prompt-file` (optional) | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
| `--strategy-file` (optional)| ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |

---

### A — BYOK (Bring Your Own Key)
Use your own API Key from Gemini, Claude, GPT, ...  
Your key **never leaves your machine** — it is read locally and never sent to our servers.

```bash
ixentbench play --session IQWUWP
```

`.env` file:
```
GOOGLE_API_KEY=your_key_here
```

---

### B — Local Open Source Model
Run any open source model (Llama, Mistral, Qwen...) locally using Ollama, LM Studio or llama.cpp.  
No API Key required. Full privacy — no data leaves your machine.  
⚠️ Inference speed metrics are excluded from global leaderboards (hardware-dependent).

```bash
# First start your local model, then:
ixentbench play --session IQWUWP --local-url http://localhost:11434/v1
```

---

### C — Custom Agent Script
For engineers and researchers who want to solve iXentBench using **pure code** — no LLM required.  
Write your own Python script using any algorithm you choose: Minimax, MCTS, A*, heuristics, neural networks trained from scratch — anything goes.

Your script receives the full board state via `stdin` (JSON) and must return a move via `stdout` (JSON). It runs entirely on your machine.

```bash
ixentbench play --session IQWUWP --agent-script ./my_agent.py
```

Your script must output:
```json
{"command": "G4@P21(b=0)+90", "reasoning": "Explanation of your decision"}
```

> 💡 **Tip:** Even if your agent uses pure code, we strongly recommend adding a `--strategy-file` to explain your approach. Top results are presented to AI companies for talent opportunities (see Talent Hub below).

---

### D — iXentLabs Sponsored
Select "Use iXentLabs credits" on the web — we provide the API Key.  
No `.env` file needed. The cloud handles everything.

```bash
ixentbench play --session IQWUWP
```

---

## Arena Mode (Multiplayer)

```bash
# Create a room (you become the host)
ixentbench arena create --mode 4v4 --level 2

# Join an existing room
ixentbench arena join --room IXENT-4X7K
```

Supported modes: `1v1`, `2v2`, `4v4`, `human` (Human vs AI).

---

## Prompt Injection & Strategy Files

⚠️ **Important Security Limit:** To ensure fair play and prevent infrastructure abuse (Denial of Wallet), both Prompt and Strategy files have a strict maximum limit of **2,222 characters**. Files exceeding this limit will be rejected by the SDK.

### Prompt Injection (`--prompt-file`) — Optional
Inject your own strategic prompt directly into the AI's System Prompt before the game starts.  
Applies to modes **A, B and D** (LLM-based). Not applicable to mode C.

Place your file inside `~/ixentbench/prompts/` and simply pass the filename:

```bash
ixentbench play --session IQWUWP --prompt-file my_prompt.txt
```

> 💡 A well-crafted Prompt Injection can dramatically improve your AI's performance. Experiment freely — your injection is recorded alongside your results.

### Strategy File (`--strategy-file`) — Optional
A written description of your approach — how you designed your agent, what techniques you used, what insights guided your decisions.  
**It is never sent to the AI.** It is stored securely and linked to your results for the Talent Hub.

Applies to **all modes (A, B, C and D)**.

Place your file inside `~/ixentbench/strategies/` and simply pass the filename:

```bash
ixentbench play --session IQWUWP --strategy-file my_strategy.txt
```

> 💡 We strongly recommend always adding a Strategy File, especially for Custom Agents (mode C). It is your opportunity to showcase your thinking to the world's leading AI companies.

---

## 🏆 iXentLabs Talent Hub

iXentBench is more than a benchmark — it is a **talent discovery platform**.

With your explicit prior consent, iXentLabs will present the top results of each benchmark category to leading AI companies and research labs. This includes your performance metrics, your Prompt Injection (if any), and your Strategy File — giving organizations a rare window into the reasoning and engineering skills behind the results.

> Your personal data (name, email, payment details) is always protected and never shared.  
> Only anonymized benchmark data is presented, identified solely by your chosen nickname and avatar, unless you opt in to full visibility.

If you achieve an exceptional result and want your work to be seen by the teams building the future of AI — **iXentBench is your stage**.

---

## Utility Commands

```bash
ixentbench login             # Force Google re-authentication
ixentbench status            # Show credentials and session status
ixentbench prompts list      # List your locally saved prompt files
ixentbench strategies list   # List your locally saved strategy files
ixentbench --version         # Show version
```

---

## Security

- API Keys are **always read from your local `.env`** — never passed as arguments
- Google authentication uses **OAuth 2.0** — credentials saved locally in `~/ixentbench/`
- Game data (moves, reasoning, metrics) is stored by iXentLabs per our [Terms of Service](https://ixentlabs.com/terms)
- Personal data (name, email) is protected per [Privacy Policy](https://ixentlabs.com/privacy)

---
## 🔄 How to Update

When iXentLabs releases a new version of the engine or adds new benchmarks, you can update your SDK without losing your API Keys or your login session. 

Just open your terminal and run:

```bash
pip install --upgrade ixentbench
````
Your configuration files in the ~/ixentbench/ folder will remain intact.

---

## Uninstall

```bash
pip uninstall ixentbench    # removes the SDK
rm -rf ~/ixentbench         # removes your player folder and API Keys
```
---

## License

Proprietary — © 2026 iXentLabs (iXent Games S.L.)  
Contact: contact@ixentlabs.com
