Metadata-Version: 2.4
Name: aiel-sdk
Version: 1.0.2
Summary: AI Execution Layer SDK (contracts + registry + decorators)
Author-email: Aldenir Flauzino <aldenirsrv@gmail.com>
License: ```text
        MIT License
        
        Copyright (c) 2025 Aldenir Flauzino
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, 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.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: typing-extensions>=4.8.0
Description-Content-Type: text/markdown

# aiel-sdk

AI Execution Layer SDK: local contracts + decorators + registry for code that runs server-side.

This package is intentionally lightweight. It provides importable symbols, typing, and a
stable contract surface that mirrors the server runtime. Your local code can type-check,
lint, and run basic smoke tests without depending on the full server implementation.

## Install

```bash
pip install aiel-sdk
```

## Quickstart

Use the `aiel.*` namespace for explicit library-style imports:

```py
from aiel.langgraph.graph import StateGraph, MessagesState, START, END
from aiel.llangchain.agents import create_agent

g = StateGraph(MessagesState).add_node("x", lambda s: s).add_edge(START, END)
app = g.compile()
print("OK", app.invoke({"messages": []}), create_agent)
```

You can also import everything from the SDK surface directly:

```py
from cae.sdk import (
  StateGraph, MessagesState, START, END, InMemorySaver,
  tools_condition, ToolNode,
  ChatPromptTemplate, PromptTemplate, Runnable, RunnableConfig,
  tool, agent, flow, flow_graph, http, mcp_server
)
```

## Core Concepts

### Contract-first SDK

This SDK mirrors the server runtime contracts. Most symbols are shims or stubs and
do not execute real server logic locally. They exist so your code can:

- import familiar library surfaces
- type-check and validate signatures
- build graphs and registry entries that the server can later execute

### Registry + decorators (travel agency example)

Use decorators to register tools, agents, flows, flow graphs, and HTTP handlers. The
registry is in-memory and used as the local source of truth before deployment.

```py
from cae.sdk import tool, agent, flow, flow_graph, http, mcp_server
from aiel.langgraph.graph import StateGraph, MessagesState, START, END, tools_condition
from aiel.langchain import ChatPromptTemplate, RunnableConfig

# Tool: discrete action callable by an agent or graph.
@tool("search_flights")
def search_flights(ctx, payload):
    origin = payload.get("origin")
    destination = payload.get("destination")
    return {"options": [{"flight": "AE101", "from": origin, "to": destination}]}

# Tool: another discrete action.
@tool("quote_hotel")
def quote_hotel(ctx, payload):
    city = payload.get("city")
    return {"hotel": "Skyline Inn", "nightly_usd": 180, "city": city}

# Agent: orchestration entry point.
@agent("travel_agent")
def travel_agent(ctx, input):
    prompt = ChatPromptTemplate.from_messages([
        {"role": "system", "content": "You are a travel agent."},
        {"role": "user", "content": input.get("request", "")},
    ])
    _ = prompt.format_messages()
    return {"intent": "plan_trip", "request": input}

# Flow: simple function flow.
@flow("daily_deals")
def daily_deals(ctx, input):
    flights = search_flights(ctx, input)
    hotels = quote_hotel(ctx, {"city": input.get("destination")})
    return {"flights": flights, "hotels": hotels}

# Flow graph: build a LangGraph-style state graph.
def build_trip_planner():
    g = StateGraph(MessagesState)
    g.add_node("agent", lambda s: s).add_edge(START, "agent").add_edge("agent", END)
    g.add_conditional_edges("agent", tools_condition, path_map={"continue": END})
    return g

flow_graph("trip_planner", build_trip_planner)

# HTTP handler: exposes a REST entry point (server-side at runtime).
@http.post("/travel/quote")
def travel_quote(ctx, body: dict):
    return daily_deals(ctx, body)

# MCP server: register tools exposed via MCP.
mcp = mcp_server("travel_agency")

@mcp.tool("search_flights")
def mcp_search_flights(ctx, origin: str, destination: str):
    return {"options": [{"flight": "AE202", "from": origin, "to": destination}]}

@mcp.tool("quote_hotel")
def mcp_quote_hotel(ctx, city: str):
    return {"hotel": "Harbor View", "nightly_usd": 210, "city": city}

# RunnableConfig is accepted by contract shims for IDE and typing support.
_config = RunnableConfig(trace_id="req-123")
```

### LangGraph contract surface

The `aiel.langgraph.graph` module mirrors core LangGraph symbols used for building
state graphs. Execution is local only for simple checks; the real runtime happens
server-side.

```py
from aiel.langgraph.graph import StateGraph, MessagesState, START, END, tools_condition

g = StateGraph(MessagesState)
g.add_node("x", lambda s: s)
g.add_edge(START, END)
app = g.compile()
print(tools_condition({}), app.invoke({"messages": []}))
```

### LangChain contract surface

The `aiel.langchain` and `aiel.llangchain` modules expose minimal prompt and runnable
shims plus placeholder agent helpers.

```py
from aiel.langchain import ChatPromptTemplate, PromptTemplate, RunnableConfig

prompt = ChatPromptTemplate.from_messages([])
print(prompt.format_messages(), RunnableConfig(trace_id="abc"))
```

## Import map

- `aiel.langgraph.graph` mirrors `langgraph.graph` surface.
- `aiel.langchain` mirrors a minimal `langchain` prompt/runnable surface.
- `aiel.llangchain.agents` mirrors agent factory helpers (contract stub).
- `cae.sdk` exposes the full SDK surface in one import (legacy or convenience).

## Explicit import mapping (LangGraph / LangChain Core / Community)

The SDK provides an explicit surface for the essential imports used in the LangGraph
customer-support tutorial. Use these as drop-in local contracts:

```py
# LangGraph
from aiel.langgraph.graph import END, StateGraph, START, InMemorySaver, ToolNode, tools_condition

# LangChain Core (contract shims provided by this SDK)
from aiel.langchain import ChatPromptTemplate, Runnable, RunnableConfig

# LangChain Core messages + runnables
from aiel.langchain_core.messages import ToolMessage
from aiel.langchain_core.runnables import RunnableLambda

# LangGraph message helpers
from aiel.langgraph.graph.message import AnyMessage, add_messages

# LangGraph checkpointer
from aiel.langgraph.checkpoint.memory import InMemorySaver

# LangChain Community tools (planned shim)
# from aiel.langchain_community.tools.tavily_search import TavilySearchResults
```

Planned mirrors for the tutorial (not yet implemented in this repo):
- `aiel.langchain_community.tools.tavily_search.TavilySearchResults`

## Project layout

- `src/cae/sdk/*` core decorators, registry, HTTP/MCP, and shim surfaces.
- `src/aiel/*` explicit `aiel.*` namespace mirror for library-style imports.
- `src/cae/examples/*` small smoke examples.

## What runs locally vs server-side

Local:
- decorators and registry updates
- basic graph wiring
- type-checking and IDE support

Server-side (not implemented in this repo):
- actual agent/tool execution
- graph runtime
- HTTP/MCP serving

## Status

![PyPI](https://img.shields.io/pypi/v/aiel-cli)
Backend integration: not implemented yet (planned per sprint output)
