Metadata-Version: 2.4
Name: anviksha
Version: 1.0.0
Summary: Anviksha Runtime Engine: adaptive AI execution runtime
Author: Anviksha Core Team
License: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Provides-Extra: all
Requires-Dist: hypothesis>=6.100; extra == 'all'
Requires-Dist: mkdocs>=1.5; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
Requires-Dist: mypy>=1.8; extra == 'all'
Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.3; extra == 'all'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy>=1.8; extra == 'lint'
Requires-Dist: ruff>=0.3; extra == 'lint'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
Description-Content-Type: text/markdown

# Anviksha Runtime Engine (ARE)

Anviksha Runtime Engine is an adaptive AI execution runtime. Applications describe intent; the runtime plans, selects capabilities, executes the plan, records state, applies policies, and returns a structured response — all without developers manually orchestrating models, tools, or workflows.

**Philosophy:** *Define the destination. The runtime decides the journey.*

---

## Quick Start

```python
from anviksha import Runtime, RuntimeConfig

# Offline mode — no LLM required
runtime = Runtime(config=RuntimeConfig(register_llm=False))

# Math → calculator (deterministic)
response = runtime.execute("2 + 3 * 4")
print(response.output)        # 14.0

# Search → retrieval (BM25)
response = runtime.execute("search for python runtime")
print(response.output)        # ranked results

# Python evaluation (safe AST)
response = runtime.execute("evaluate sum(range(100))")
print(response.output)        # 4950

# Async
import asyncio
response = asyncio.run(runtime.aexecute("2 ** 10"))
print(response.output)        # 1024

# Inspect execution
print(response.status)        # succeeded
print(response.diagnostics)   # planner decisions
print(response.metadata)      # timeline, events, cost
```

---

## Architecture

```
Application
    │
    ▼
┌─────────────────────────────────────┐
│         Runtime (SDK)               │
│  execute / aexecute / astream       │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│         Planner                     │
│  classifies intent, selects caps    │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      Policy Engine                  │
│  validates plan & response          │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      Execution Engine               │
│  parallel step execution + retry    │
└─────────────────────────────────────┘
    │                           │
    ▼                           ▼
┌──────────┐           ┌──────────────┐
│ Capability│◄─────────│ State Manager│
│ Registry  │  events  │ + SQLite     │
└──────────┘           └──────────────┘
```

10 RFCs implemented: Runtime Architecture, Execution Lifecycle, Planner, Capability Registry, Execution Engine, Policy Engine, State Manager, Observability, Plugin SDK, Public Python SDK.

---

## Features

| Feature | Status |
|---|---|
| Intent classification (9 types) | ✅ |
| Safe AST-based calculator | ✅ |
| Text retrieval (BM25) | ✅ |
| Session memory (key-value) | ✅ |
| Safe Python evaluation | ✅ |
| HTTP fetch capability | ✅ |
| Sandboxed filesystem | ✅ |
| HTTP LLM capability (OpenAI-compatible) | ✅ |
| Parallel step execution | ✅ |
| Retry with exponential backoff | ✅ |
| Plan validation (dependencies, capability existence) | ✅ |
| Minimum confidence policy | ✅ |
| Immutable state timeline | ✅ |
| SQLite persistent state | ✅ |
| Structured observability events | ✅ |
| OpenTelemetry export (optional) | ✅ |
| Plugin auto-discovery (entry points) | ✅ |
| No silent fallbacks — every error is actionable | ✅ |

---

## Configuration

| Variable | Default | Description |
|---|---|---|
| `ANVIKSHA_LLM_API_BASE` | — | OpenAI-compatible API base URL |
| `ANVIKSHA_LLM_API_KEY` | — | API key |
| `ANVIKSHA_LLM_MODEL` | — | Model name |
| `ANVIKSHA_MAX_RETRIES` | `3` | Max capability retry attempts |
| `ANVIKSHA_RETRY_BASE_DELAY_S` | `1.0` | Initial retry backoff |
| `ANVIKSHA_RETRY_MAX_DELAY_S` | `30.0` | Maximum retry delay |
| `ANVIKSHA_STATE_DB_PATH` | — | SQLite path for persistence |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OpenTelemetry endpoint |

---

## Performance

```
Benchmark                     Ops/sec
─────────────────────────────────────
Calculator throughput          4,727/s
Python evaluation             26,068/s
Memory operations            749,597/s
Retrieval (1000 docs)            155/s
p50 latency                     0.13ms
```

---

## Testing

96 tests (49 original + 47 new Phase 2) — unit, integration, concurrency, property-based.

```bash
pip install -e ".[dev]"
pytest tests/ -v --cov
```

---

## Project Structure

```
src/anviksha/
├── __init__.py
├── config.py                  # Env-based RuntimeSettings
├── exceptions.py              # Exception hierarchy
├── types.py                   # Immutable data models
├── capabilities/
│   ├── base.py                # Capability protocol & metadata
│   ├── registry.py            # Filtering/sorting registry
│   ├── builtins.py            # AST calculator
│   ├── llm.py                 # HTTP LLM capability
│   ├── retrieval.py           # BM25 text retrieval
│   ├── memory.py              # In-memory key-value store
│   ├── python_exec.py         # Safe Python evaluation
│   ├── http_client.py         # HTTP fetch capability
│   └── filesystem.py          # Sandboxed file I/O
├── execution/engine.py        # Parallel execution + retry
├── observability/events.py    # Structured event sink
├── planner/default.py         # Rule-based intent classifier
├── plugins/sdk.py             # Plugin protocol & metadata
├── plugins/discovery.py       # Entry-point auto-discovery
├── policy/engine.py           # Policy engine + min confidence
├── sdk/runtime.py             # Public Runtime API
└── state/manager.py           # Immutable state timeline
    state/persistence.py       # SQLite persistent state
```

---

## License

MIT
