Metadata-Version: 2.4
Name: neurop-forge-sdk
Version: 2.1.0
Summary: Neurop Forge SDK - Execute 5,175+ pre-verified, hash-locked function blocks across 5 domains
Author-email: Lourens Wasserman <wassermanlourens@gmail.com>
License: MIT
Project-URL: Homepage, https://neurop-forge.onrender.com
Project-URL: Documentation, https://github.com/Louw115/neurop-forge
Project-URL: Repository, https://github.com/Louw115/neurop-forge
Project-URL: Bug Tracker, https://github.com/Louw115/neurop-forge/issues
Keywords: ai,agents,execution,deterministic,audit,compliance,blocks,governance
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.8
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.21; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# Neurop Forge SDK

**Execute 5,175+ pre-verified, hash-locked function blocks across 5 domains — with full audit trail.**

Neurop Forge is an AI-native execution control layer. AI agents search, compose, and execute blocks — but never modify them. Every execution is deterministic, cryptographically auditable, and policy-governed.

## Installation

```bash
pip install neurop-forge-sdk
```

## Quick Start

```python
from neuropforge import NeuropForge

client = NeuropForge(api_key="your_api_key")

# Execute a block by exact name — deterministic, auditable
result = client.execute("to_uppercase", text="hello world")
print(result.result)       # "HELLO WORLD"
print(result.audit_hash)   # cryptographic proof of execution

# Search for blocks by natural language
blocks = client.search("validate email address")
for block in blocks:
    print(f"{block.name} [{block.domain}] — {block.why_selected}")

# Browse domains
for domain in client.domains():
    print(f"{domain.domain}: {domain.block_count} blocks")
```

## Domains

Neurop Forge organizes 5,175+ blocks into 5 domains:

| Domain | Blocks | Examples |
|--------|--------|----------|
| **data** | 4,552 | String ops, math, validation, collections, date/time |
| **crypto** | 218 | Hashing, wallet generation, gas fee calculation |
| **integrations** | 164 | Webhook triggers, API calls, message formatting |
| **payments** | 137 | Transaction validation, fee calculation, refund processing |
| **auth** | 104 | Token generation, password hashing, permission checks |

```python
# List blocks in a specific domain
crypto_blocks = client.domain_blocks("crypto", limit=10)
for block in crypto_blocks:
    print(f"{block.name}: {block.description}")
```

## Async Client

For asyncio-based agent frameworks (LangChain, CrewAI, AutoGen):

```python
from neuropforge import AsyncNeuropForge

async with AsyncNeuropForge(api_key="your_api_key") as client:
    result = await client.execute("calculate_gas_fee", gas_limit=21000, gas_price_gwei=30.5)
    print(result.result)  # 0.0006405

    domains = await client.domains()
    blocks = await client.search("validate payment amount")
```

## LangChain Integration

Use Neurop Forge as a LangChain tool for controlled AI execution:

```python
from langchain.tools import tool
from neuropforge import NeuropForge

client = NeuropForge(api_key="your_api_key")

@tool
def neurop_execute(block_name: str, inputs: dict) -> str:
    """Execute a pre-verified Neurop Forge block. The AI cannot generate
    arbitrary code — it can only call verified blocks by exact name."""
    result = client.execute(block_name, **inputs)
    return str(result.result)

@tool
def neurop_search(query: str) -> str:
    """Search the Neurop Forge library for blocks matching a natural language query."""
    results = client.search(query, limit=5)
    return "\n".join(f"{r.name} [{r.domain}]: {r.why_selected}" for r in results)
```

## CLI

The `nf` command-line tool is included for testing and exploration:

```bash
# Set your API key
export NEUROP_API_KEY="your_api_key"

# Check API health
nf health

# Browse domains
nf domains -v

# List blocks in a domain
nf domain-blocks crypto --limit 10 -v

# Search for blocks
nf search "validate email" -v

# Execute a block
nf exec to_uppercase --input text="hello world"

# Execute with JSON input
nf exec calculate_gas_fee --json '{"gas_limit": 21000, "gas_price_gwei": 30.5}'

# Get library statistics
nf stats

# Verify audit chain integrity
nf audit
```

## API Key Management

```python
from neuropforge import NeuropForge

# Register a new API key (no auth required for this call)
client = NeuropForge(api_key="temp_key")
result = client.register_key(name="My App", email="dev@example.com")
print(result["api_key"])  # Your new API key

# Use the new key
client = NeuropForge(api_key=result["api_key"])

# Get key metadata
info = client.key_info()
print(info)  # {"name": "My App", "email": "dev@example.com", ...}

# Get usage statistics
usage = client.usage()
print(usage)  # {"total_requests": 42, "recent": [...]}

# Rotate key
rotated = client.rotate_key(current_key=result["api_key"])
print(rotated["new_api_key"])

# Revoke key
client.revoke_key()
```

## Configuration

Set your API key via environment variable:

```bash
export NEUROP_API_KEY="your_api_key"
```

Or pass it directly:

```python
client = NeuropForge(api_key="your_api_key")
```

Custom API endpoint (for self-hosted deployments):

```python
client = NeuropForge(
    api_key="your_api_key",
    base_url="https://your-instance.example.com",
    timeout=60.0
)
```

## API Reference

### `NeuropForge(api_key, base_url, timeout)`

Initialize the sync client. Supports context manager (`with`).

### `AsyncNeuropForge(api_key, base_url, timeout)`

Initialize the async client. Supports async context manager (`async with`).

### Methods (sync and async)

| Method | Description | Returns |
|--------|-------------|---------|
| `execute(block_name, **inputs)` | Execute a block by exact name | `ExecutionResult` |
| `search(query, limit)` | Search blocks by natural language | `List[SearchResult]` |
| `domains()` | List all domains with block counts | `List[DomainInfo]` |
| `domain_blocks(domain, limit)` | List blocks in a domain | `List[BlockInfo]` |
| `list_blocks(limit, category)` | List available blocks | `List[BlockInfo]` |
| `health()` | Check API health | `dict` |
| `stats()` | Get library statistics | `dict` |
| `audit_chain()` | Get audit chain info | `dict` |
| `register_key(name, email)` | Register a new API key | `dict` |
| `rotate_key(current_key)` | Rotate an existing API key | `dict` |
| `revoke_key()` | Revoke the current API key | `dict` |
| `key_info()` | Get current API key metadata | `dict` |
| `usage()` | Get usage data for current key | `dict` |

### Data Classes

- **`ExecutionResult`**: `success`, `block_name`, `result`, `execution_time_ms`, `audit_hash`
- **`SearchResult`**: `name`, `domain`, `operation`, `why_selected`
- **`BlockInfo`**: `name`, `category`, `description`, `inputs`, `domain`
- **`DomainInfo`**: `domain`, `block_count`, `description`

### Exceptions

- **`NeuropForgeError`**: Base exception
- **`BlockNotFoundError`**: Block doesn't exist
- **`ExecutionError`**: Block execution failed
- **`AuthenticationError`**: Invalid or missing API key
- **`RateLimitError`**: Rate limit exceeded

## Why Neurop Forge?

- **Deterministic**: Same inputs always produce same outputs
- **Auditable**: Every execution has a cryptographic audit hash
- **Secure**: AI can only execute verified blocks, never arbitrary code
- **Compliant**: Designed for SOC 2, HIPAA, PCI-DSS environments
- **Domain-organized**: 5 domains for clear separation of concerns

## License

MIT
