Metadata-Version: 2.4
Name: aethershell
Version: 1.5.0
Summary: AetherShell - AI-powered typed shell with workflow orchestration and cloud deployment
Author-email: nervosys <contact@nervosys.ai>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/nervosys/AetherShell
Project-URL: Documentation, https://github.com/nervosys/AetherShell/blob/master/integrations/python/README.md
Project-URL: Repository, https://github.com/nervosys/AetherShell
Project-URL: Issues, https://github.com/nervosys/AetherShell/issues
Keywords: shell,ai,agent,pipeline,llm,automation,workflow,serverless,cloud
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
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: Topic :: Software Development :: Interpreters
Classifier: Topic :: System :: Shells
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1; extra == "langchain"
Requires-Dist: pydantic>=2.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index>=0.10; extra == "llamaindex"
Provides-Extra: cloud
Requires-Dist: boto3>=1.28.0; extra == "cloud"
Requires-Dist: azure-functions>=1.15.0; extra == "cloud"
Requires-Dist: functions-framework>=3.0; extra == "cloud"
Requires-Dist: fastapi>=0.100.0; extra == "cloud"
Requires-Dist: uvicorn>=0.23.0; extra == "cloud"
Provides-Extra: all
Requires-Dist: langchain>=0.1; extra == "all"
Requires-Dist: pydantic>=2.0; extra == "all"
Requires-Dist: llama-index>=0.10; extra == "all"
Requires-Dist: boto3>=1.28.0; extra == "all"
Requires-Dist: azure-functions>=1.15.0; extra == "all"
Requires-Dist: functions-framework>=3.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn>=0.23.0; extra == "all"

# AetherShell Python SDK

Python bindings for AetherShell - AI-powered typed shell with workflow orchestration and cloud deployment.

## Installation

```bash
# Core SDK
pip install aethershell

# With LangChain integration
pip install aethershell[langchain]

# With cloud deployment support
pip install aethershell[cloud]

# Everything
pip install aethershell[all]
```

Or from a checkout of the repository:

```bash
pip install ./integrations/python
```

Requires the `ae` binary on `PATH`. Install it with
`cargo install aethershell`, or take a prebuilt binary from the
[releases page](https://github.com/nervosys/AetherShell/releases).

> **Versioning:** this SDK versions independently of the `ae` shell — SDK 1.5.0
> is current against shell 4.1.0.

## Quick Start

```python
from aethershell import AetherRuntime, Agent

# Create runtime
runtime = AetherRuntime()

# Evaluate AetherShell code
result = runtime.eval('[1, 2, 3] | map(fn(x) => x * 2)')
print(result)  # [2, 4, 6]

# Create and run an agent
agent = runtime.create_agent(
    name="researcher",
    model="openai:gpt-4o",
    tools=["http_get", "search"]
)

result = await agent.run("Find the latest Python release version")
print(result)
```

## Features

- **Evaluation**: Execute AetherShell code from Python
- **Pipelines**: Process data with typed pipelines
- **Agents**: Create and orchestrate AI agents
- **Swarms**: Multi-agent coordination
- **Workflows**: MapReduce, Saga, Fan-Out patterns
- **Metrics**: Prometheus metrics, tracing, health checks
- **Distributed**: Service discovery, leader election, load balancing
- **Cloud**: Deploy as serverless functions (AWS, Azure, GCP, K8s)
- **LangChain**: Full LangChain tool integration

## Workflow Orchestration

```python
from aethershell.workflows import (
    MapReduceWorkflow,
    SagaWorkflow,
    PipelineWorkflow,
    CircuitBreaker,
)

# MapReduce for parallel processing
workflow = MapReduceWorkflow(
    name="word_count",
    map_fn=lambda text: len(text.split()),
    reduce_fn=lambda a, b: a + b,
)
result = await workflow.run(["hello world", "foo bar baz"])
print(result.result)  # 5

# Saga with compensation
saga = SagaWorkflow("order")
saga.add_saga_step("reserve", reserve_inventory, rollback_reservation)
saga.add_saga_step("charge", charge_payment, refund_payment)
saga.add_saga_step("ship", ship_order, cancel_shipment)
result = await saga.run(order_data)

# Circuit breaker for fault tolerance
breaker = CircuitBreaker(name="api", failure_threshold=5)
result = breaker.call(lambda: api_request())
```

## Metrics & Observability

```python
from aethershell.metrics import (
    MetricsCollector,
    Counter,
    Gauge,
    Histogram,
    Tracer,
)

# Create metrics
collector = MetricsCollector(namespace="myapp")
requests = collector.counter("requests_total")
latency = collector.histogram("request_latency_seconds")

# Track metrics
requests.inc()
latency.observe(0.125)

# Export to Prometheus
print(collector.to_prometheus())

# Distributed tracing
tracer = collector.tracer("my-service")
with tracer.start_span("handle_request") as span:
    span.set_attribute("user_id", "123")
    # ... process request
```

## Distributed Agents

```python
from aethershell.distributed import (
    ServiceRegistry,
    LeaderElection,
    LoadBalancer,
    DistributedSwarm,
)

# Service discovery
registry = ServiceRegistry()
registry.register("agent-nlp", "host1", 8080)
registry.register("agent-nlp", "host2", 8080)

# Load balancing
lb = LoadBalancer(registry, strategy="round_robin")
service = lb.select_service("agent-nlp")

# Leader election
election = LeaderElection("node-1", registry, "cluster")
await election.run_election()
if election.is_leader:
    print("I am the leader!")

# Distributed swarm
swarm = DistributedSwarm("my-swarm", registry)
swarm.add_local_agent(my_agent)
result = await swarm.dispatch(goal="analyze data", capability="nlp")
```

## Cloud Deployment

Deploy agents as serverless functions:

```python
from aethershell.cloud import (
    CloudProvider,
    FunctionConfig,
    DeploymentConfig,
    deploy_agent,
)

# Configure function
config = DeploymentConfig(
    provider=CloudProvider.AWS_LAMBDA,
    region="us-east-1",
    function_config=FunctionConfig(
        name="my-agent",
        memory_mb=512,
        timeout_seconds=60,
    ),
)

# Generate deployment files
agent_code = '''
def create_agent(runtime):
    return Agent(name="analyst", model="openai:gpt-4o", runtime=runtime)
'''

files = deploy_agent(config, agent_code, output_dir="./deploy")
# Creates: handler.py, template.yaml, samconfig.toml, requirements.txt
```

Supported platforms:
- **AWS Lambda** (SAM template)
- **Azure Functions** (Bicep)
- **GCP Cloud Functions** (Terraform)
- **Kubernetes/Knative** (manifests + Skaffold)

## LangChain Integration

```python
from aethershell.langchain import (
    get_all_aethershell_tools,
    AetherWorkflowTool,
    AetherMapReduceTool,
    AetherMetricsTool,
)

# Get all tools for LangChain agent
tools = get_all_aethershell_tools()

# Use with LangChain
from langchain.agents import initialize_agent
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
agent.run("Process this data with MapReduce: [1,2,3,4,5]")
```

## API Reference

### AetherRuntime

```python
runtime = AetherRuntime()

# Evaluate code
result = runtime.eval(code: str) -> Any

# Create agent
agent = runtime.create_agent(
    name: str,
    model: str = "openai:gpt-4o-mini",
    tools: List[str] = [],
    max_steps: int = 10
) -> Agent

# Run swarm
result = await runtime.run_swarm(
    agents: List[Agent],
    goal: str,
    policy: str = "round_robin",
    max_iterations: int = 10
) -> SwarmResult
```

### Agent

```python
agent = Agent(name="agent1", model="openai:gpt-4o")

# Run agent
result = await agent.run(goal: str) -> AgentResult

# Get trace
trace = agent.trace  # List of steps taken
```

### A2UI Events

```python
# Subscribe to events
def on_event(event: A2UIEvent):
    print(f"Event: {event.type}")

runtime.subscribe_a2ui(on_event)

# Event types
# - Notify: Notifications
# - Progress: Progress updates
# - Prompt: User prompts
# - AgentThinking: Agent reasoning
```

## Development

```bash
# Clone repository
git clone https://github.com/nervosys/AetherShell.git
cd AetherShell/integrations/python

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Build package
python -m build
```

## License

AGPL-3.0-or-later with commercial dual-license option — see [LICENSE](../../LICENSE) for details.
