Metadata-Version: 2.4
Name: astra-framework
Version: 0.1.2
Summary: Astra Framework - Core APIs and abstractions for building AI agents, teams, RAG pipelines, and workflows
Project-URL: Homepage, https://github.com/HeeManSu/astra-agi
Project-URL: Documentation, https://github.com/HeeManSu/astra-agi#readme
Project-URL: Repository, https://github.com/HeeManSu/astra-agi
Project-URL: Issues, https://github.com/HeeManSu/astra-agi/issues
Author-email: Himanshu Sharma <himanshu.kumarr07@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,ai-agents,framework,llm,multi-agent,rag,retrieval-augmented-generation
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: astra-observability>=0.1.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: greenlet>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lancedb>=0.4.0
Requires-Dist: mcp>=1.26.0
Requires-Dist: motor>=3.3.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter>=0.21.0
Provides-Extra: all
Requires-Dist: aioboto3>=12.0.0; extra == 'all'
Requires-Dist: beanie>=1.24.0; extra == 'all'
Requires-Dist: boto3>=1.35.0; extra == 'all'
Requires-Dist: motor>=3.3.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: aioboto3>=12.0.0; extra == 'aws'
Requires-Dist: boto3>=1.35.0; extra == 'aws'
Provides-Extra: mongodb
Requires-Dist: beanie>=1.24.0; extra == 'mongodb'
Requires-Dist: motor>=3.3.0; extra == 'mongodb'
Description-Content-Type: text/markdown

# astra-framework

**The execution engine for compiler-based multi-agent AI.** Instead of ReAct loops where the LLM decides each step at runtime, Astra compiles the execution plan from a single planning call, runs the typed graph deterministically, and uses one final call to synthesize the response. Three model calls per query, no matter how many tools the workflow involves.

```
LLM call → restricted Python → AST validation → ExecutionGraph → deterministic run
```

---

## Why Not ReAct?

| | ReAct / Tool-calling | Astra |
|---|---|---|
| LLM calls per task | Unbounded (N loops) | **Fixed: 3 calls (planner + code-gen + synthesize)** |
| Execution path | Decided at runtime | **Compiled upfront** |
| Tool call order | Non-deterministic | **Guaranteed** |
| Debuggability | Hard. Emergent behavior | **Inspect the graph before running** |
| Token cost | Grows with task complexity | **Constant** |

---

## Installation

```bash
pip install astra-framework
```

**Optional extras:**

```bash
pip install astra-framework[aws]      # AWS Bedrock (Claude, etc.)
pip install astra-framework[mongodb]  # MongoDB storage backend
pip install astra-framework[all]      # Everything
```

**Requires:** Python 3.10+

---

## Quick Start

```python
from framework import Agent, Sandbox, build_entity_semantic_layer, generate_stubs
from framework.models import Gemini

# 1. Define your agents with tools
market_analyst = Agent(
    name="market_analyst",
    model=Gemini("gemini-2.0-flash"),
    instructions="Analyse stock fundamentals and price trends.",
    tools=[get_stock_price, get_financials],
)

risk_officer = Agent(
    name="risk_officer",
    model=Gemini("gemini-2.0-flash"),
    instructions="Evaluate investment risk.",
    tools=[calculate_risk_score],
)

# 2. Build the semantic layer (describes your team to the compiler)
semantic_layer = build_entity_semantic_layer(
    agents=[market_analyst, risk_officer],
    task="Analyse AAPL and assess investment risk",
)

# 3. Generate stubs (typed Python signatures the LLM can reason over)
stubs = generate_stubs(semantic_layer)

# 4. Run the compiler. Three model calls total (planner + code-gen + synthesize).
sandbox = Sandbox(agents=[market_analyst, risk_officer])
result = await sandbox.execute(semantic_layer=semantic_layer, stubs=stubs)

print(result.output)   # Final answer
print(result.plan)     # The compiled ExecutionGraph. Inspect it.
```

---

## Core Concepts

### Semantic Layer

The semantic layer translates your agents and their tools into a typed schema the compiler can reason over. It captures:
- What each agent does (instructions)
- What tools it has (name, parameters, return type)
- What the overall task is

```python
from framework import build_entity_semantic_layer

semantic_layer = build_entity_semantic_layer(
    agents=[analyst, risk_officer, memo_writer],
    task="Full investment analysis for AAPL",
)
```

### Compiler

The compiler takes the semantic layer and produces a restricted Python program, then validates it against an AST whitelist before lowering it to an `ExecutionGraph`. Only a safe subset of Python is allowed (no imports, no file I/O, no network calls): just tool calls and data flow.

```
semantic_layer
    → LLM generates restricted Python
    → AST parser validates (banned nodes, nesting limits, tool whitelist)
    → plan_builder lowers to ExecutionGraph
    → plan_validator checks graph structure
```

### Sandbox

The `Sandbox` executes the validated `ExecutionGraph` deterministically. Each node in the graph maps to a tool call on a specific agent. The executor dispatches calls in order, passes results between nodes, and collects the final output.

```python
result = await sandbox.execute(semantic_layer=semantic_layer, stubs=stubs)

result.output        # str: the final answer
result.plan          # ExecutionGraph: the compiled plan
result.tool_calls    # list: every tool call made, in order
result.duration_ms   # int: total wall-clock time
```

### MCP Support

Agents can use tools from any MCP (Model Context Protocol) server:

```python
from framework.tool.mcp import MCPToolkit

exa_toolkit = MCPToolkit(
    name="exa",
    slug="exa-search",
    command="npx",
    args=["-y", "exa-mcp-server"],
)

analyst = Agent(
    name="analyst",
    tools=[exa_toolkit],
    ...
)
```

---

## API Reference

### `build_entity_semantic_layer(agents, task)`

Builds a typed `EntitySemanticLayer` from a list of `Agent` instances and a task string.

### `build_domain_schema(semantic_layer)`

Converts an `EntitySemanticLayer` into a `DomainSchema`, the structured representation used by the compiler.

### `generate_stubs(semantic_layer)`

Generates Python stub code from the semantic layer. The stubs give the LLM typed function signatures to write against during the planning call.

### `Sandbox(agents)`

The execution engine. Call `.execute(semantic_layer, stubs)` to run the full compiler pipeline and return a `SandboxResult`.

### `SandboxResult`

| Field | Type | Description |
|---|---|---|
| `output` | `str` | Final answer |
| `plan` | `ExecutionGraph` | The compiled plan |
| `tool_calls` | `list[ToolCall]` | Every call made, in order |
| `duration_ms` | `int` | Total execution time |
| `error` | `str \| None` | Error message if execution failed |

### `Agent(name, model, instructions, tools, memory)`

An agent with a model, instructions, and tools. Agents are passive; the `Sandbox` drives their execution according to the compiled plan.

### `Memory(num_history_turns)`

Conversation memory. Plugs into `Agent` to include recent history in context.

---

## Model Support

| Provider | Import |
|---|---|
| Google Gemini | `from framework.models import Gemini` |
| OpenAI GPT | `from framework.models import OpenAI` |
| AWS Bedrock | `from framework.models.aws import Bedrock` |

---

## Related Packages

| Package | Role |
|---|---|
| [`astra-runtime`](../runtime) | FastAPI server that hosts your agents over HTTP |
| [`astra-observability`](../observability) | Tracing, spans, and telemetry |

---

## License

[MIT](LICENSE). Copyright © 2025 Himanshu Sharma
