Metadata-Version: 2.4
Name: hivekit
Version: 0.1.0
Summary: Toolkits for using hive agents, including CLI and SDK.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=5.1
Requires-Dist: pydantic>=1.8.2
Requires-Dist: gitpython>=3.1.24
Requires-Dist: rich>=12.5.1
Requires-Dist: kubernetes>=33.1.0
Requires-Dist: portforward>=0.3.0
Requires-Dist: argcomplete>=3.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: authlib>=1.2.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: py-machineid>=0.6.0
Requires-Dist: cryptography>=42.0.0
Dynamic: license-file

```
       ███          █████   █████  ███                       █████   ████  ███   █████
      ░░░███       ░░███   ░░███  ░░░                       ░░███   ███░  ░░░   ░░███
        ░░░███      ░███    ░███  ████  █████ █████  ██████  ░███  ███    ████  ███████
          ░░░███    ░███████████ ░░███ ░░███ ░░███  ███░░███ ░███████    ░░███ ░░░███░
           ███░     ░███░░░░░███  ░███  ░███  ░███ ░███████  ░███░░███    ░███   ░███
         ███░       ░███    ░███  ░███  ░░███ ███  ░███░░░   ░███ ░░███   ░███   ░███ ███
       ███░         █████   █████ █████  ░░█████   ░░██████  █████ ░░████ █████  ░░█████
      ░░░          ░░░░░   ░░░░░ ░░░░░    ░░░░░     ░░░░░░  ░░░░░   ░░░░ ░░░░░    ░░░░░
```

<div align="center">

**> HiveKit**

Command-line interface for managing Hive AI agent experiments

[![PyPI version](https://badge.fury.io/py/hivekit.svg)](https://badge.fury.io/py/hivekit)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Installation](#installation) • [Quick Start](#quick-start) • [Commands](#commands-reference) • [Configuration](#configuration-guide)

</div>

## Installation

```bash
pip install hivekit
```

**Requirements:** Python 3.12+

**From source:**
```bash
git clone https://github.com/hiverge/hivekit.git
cd hivekit
source start.sh
```

## Quick Start

**1. Initialize and authenticate:**
```bash
# Initialize config with your organization ID
hive init

# Authenticate with Hive platform
hive login
```

**2. Create your experiment configuration file:**

Create a `hive.yaml` file in your project directory:
```yaml
version: v1alpha1
experiment_name: my-experiment-  # '-' suffix generates unique ID

repo:
  source: https://github.com/your-org/your-repo.git
  branch: main
  evaluation_script: evaluation.py
  target_code:
    - main.py

runtime:
  num_agents: 1
  max_runtime_seconds: -1  # -1 = unlimited
  max_iterations: -1       # -1 = unlimited

sandbox:
  base_image: python:3.9-slim
  setup_script: |
    pip install -r requirements.txt
  evaluation_timeout: 60
  resources:
    cpu: "2"
    memory: 4Gi
```

**3. Create and manage experiments:**
```bash
# Create an experiment from config file
hive create exp -f hive.yaml

# Create with overrides
hive create exp -f hive.yaml repo.branch=dev sandbox.resources.cpu=1

# List all experiments
hive list exp

# Get experiment details
hive get exp my-experiment-abc123

# Delete experiment
hive delete exp my-experiment-abc123
```

## Commands Reference

### Setup & Authentication
```bash
hive init                    # Initialize configuration with organization ID
hive login                   # Authenticate with Hive platform
hive logout                  # Clear stored credentials
```

### Experiment Management
```bash
hive create exp -f <config>             # Create experiment from config file
hive create exp -f <config> key=value   # Create with config overrides
hive list exp                           # List all experiments
hive get exp <name>                     # Get detailed experiment information
hive delete exp <name>                  # Delete single experiment
```

### Batch Operations
```bash
# Delete multiple experiments
hive delete exp exp-1 exp-2 exp-3

# Skip confirmation with -y flag
hive delete exp exp-1 exp-2 exp-3 -y
```

**Example output:**
```
experiment "exp-1" deleted
experiment "exp-2" deleted
experiment "exp-3" deleted
Total: 3 deleted
```

### Help
```bash
hive --help                  # Show all commands
hive <command> --help        # Show help for specific command
```

## Configuration Guide

### Config File Locations
- **User config:** `~/.hive/config.yaml` - stores organization_id (created by `hive init`)
- **Experiment config:** `hive.yaml` in your project - required for creating experiments

### Creating Experiments with Config Overrides

You can override any config value when creating an experiment:
```bash
# Override single values
hive create exp -f hive.yaml repo.branch=feature/new-feature

# Override multiple values
hive create exp -f hive.yaml \
  repo.branch=dev \
  sandbox.resources.cpu=1 \
  runtime.num_agents=5

# Override experiment name
hive create exp -f hive.yaml experiment_name=test-run-
```

### Configuration Sections

#### **Experiment Name**
```yaml
experiment_name: my-experiment-  # '-' suffix generates unique hash
```
Add a `-` suffix to auto-generate a unique ID (e.g., `my-experiment-abc123`).

#### **Repository** (`repo`)
Defines the code repository for your experiments:
```yaml
repo:
  source: https://github.com/your-org/repo.git   # Git repository URL
  branch: main                                    # Branch to use
  evaluation_script: evaluation.py                # Script that evaluates results
  target_code:                                    # YAML list of files (required)
    - main.py
    - utils.py
    - file.py:1-10                                # Optional: specify line ranges
  github_token_variable: GITHUB_TOKEN             # Optional: env var for PAT
```

**Private repositories:** Use `github_token_variable` to reference an environment variable containing your GitHub Personal Access Token:
```bash
export GITHUB_TOKEN=ghp_your_token_here
hive create exp -f hive.yaml
```

#### **Runtime** (`runtime`)
Controls experiment execution:
```yaml
runtime:
  num_agents: 10              # Number of parallel agents
  max_runtime_seconds: 3600   # Max execution time (-1 = unlimited)
  max_iterations: 100         # Max iterations per agent (-1 = unlimited)
```

#### **Sandbox** (`sandbox`)
Defines the execution environment:
```yaml
sandbox:
  base_image: python:3.9-slim  # Docker base image
  setup_script: |              # Required: commands to run on startup
    pip install -r requirements.txt
  evaluation_timeout: 60       # Max time for evaluation script in seconds
  resources:
    cpu: "2"                   # CPU request/limit
    memory: 4Gi                # Memory limit
```

### Environment Variables
- `EDITOR` - Text editor for `hive edit config` (default: vim)

## Understanding Experiments

### Experiment Lifecycle
1. **Pending** - Experiment submitted, waiting to start
2. **ImageBuilding** - Building container images
3. **InProgress** - Agents are being initialized
4. **Running** - Agents are executing experiments
5. **Completed** - All agents finished successfully

### List Output
```
NAME                  AGENTS  STATUS          AGE
my-experiment-abc123  10/10  Running         5m
test-exp-xyz789       0/10   ImageBuilding   2h
debug-exp-abc789      5/10   InProgress      15m
```

- **AGENTS**: Shows `ready/total` (e.g., `8/10` = 8 agents ready out of 10)
- **STATUS**: Current experiment phase (Pending → ImageBuilding → InProgress → Running → Completed)
- **AGE**: Time since creation

### Get Experiment Details
```
$ hive get exp my-experiment-abc123

apiversion: v1alpha1
name: my-experiment-abc123
spec
  repo
    source:             https://github.com/your-org/repo.git
    branch:             main
    evaluation_script:  evaluation.py
    target_code:
      - main.py
      - utils.py
  runtime
    agents:          10/10
    max_runtime:     -1
    max_iterations:  -1
  sandbox
    base_image:          python:3.9-slim
    evaluation_timeout:  60s
    setup_script:
      pip install -r requirements.txt
    resources:
      cpu:    2
      memory: 4Gi
status
  created: 2026-04-22T10:30:00Z (2h ago)
  phase:   Running
  message: Experiment is running successfully
```

**Output sections:**
- **name**: Experiment identifier (auto-generated if name ended with `-`)
- **spec**: Experiment specification
  - **repo**: Source code repository configuration
    - **target_code**: Files for agents to focus on (can be single file or list)
  - **runtime**: Execution settings (agents shows ready/total, e.g., 10/10)
  - **sandbox**: Container environment and resources
- **status**: Current state
  - **created**: Creation timestamp and age
  - **phase**: Current lifecycle phase
  - **message**: Condition message (if available)

## Development

**Setup:**
```bash
git clone https://github.com/hiverge/hivekit.git
cd hivekit
source start.sh
```

**Testing:**
```bash
uv pip install -e ".[test]"
make test
```

**Linting:**
```bash
uv pip install -e ".[lint]"
make lint
```

## Support

- 📖 [Documentation](https://docs.hiverge.io)
- 🐛 [Issues](https://github.com/hiverge/hivekit/issues)

## License

MIT License - see [LICENSE](LICENSE)
