Metadata-Version: 2.4
Name: heaven-framework
Version: 0.1.6
Summary: HEAVEN - Hierarchical, Embodied, Autonomously Validating Evolution Network
Home-page: https://github.com/heaven-framework/heaven
Author: HEAVEN Team
Author-email: HEAVEN Team <heaven@example.com>
License: MIT
Project-URL: Homepage, https://github.com/sancovp/heaven-framework
Project-URL: Repository, https://github.com/sancovp/heaven-framework.git
Project-URL: Documentation, https://heaven-framework.readthedocs.io
Project-URL: Issues, https://github.com/sancovp/heaven-framework/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-adk>=0.2.0
Requires-Dist: google-genai>=1.11.0
Requires-Dist: langchain-anthropic>=0.3.13
Requires-Dist: langchain-core>=0.3.65
Requires-Dist: langchain-deepseek>=0.1.2
Requires-Dist: langchain-google-genai>=2.1.5
Requires-Dist: langchain-groq>=0.2.4
Requires-Dist: langchain-openai>=0.3.22
Requires-Dist: langchain>=0.1.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: litellm>=1.67.5
Requires-Dist: pydantic==2.10.6
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.24.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: ruff>=0.1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# HEAVEN Base Framework

**H**ierarchical, **E**mbodied, **A**utonomously **V**alidating **E**volution **N**etwork

HEAVEN Base is the foundational framework for building autonomous AI agents with cross-framework compatibility, event-driven architecture, and self-modifying capabilities. This is the core library that powers the HEAVEN metaprogrammatic agent framework where prompts, tools, agents, and code can all generate each other.

## Features

- **Cross-Framework Support**: Works with both LangChain and Google ADK backends
- **Unified Event System**: Standardized HEAVEN events for consistent agent communication
- **Flexible Agent Architecture**: Build custom agents by extending `BaseHeavenAgent`
- **Tool System**: Create reusable tools by extending `BaseHeavenTool`
- **History Management**: Advanced history tracking with event extraction
- **Multiple LLM Providers**: Support for OpenAI, Anthropic, Google, DeepSeek, Groq, and more

## Installation

```bash
pip install heaven-base
```

## Quick Start

### Creating a Simple Agent

```python
from heaven_base import BaseHeavenAgent, HeavenAgentConfig

class MyAgent(BaseHeavenAgent):
    @classmethod
    def get_default_config(cls) -> HeavenAgentConfig:
        return HeavenAgentConfig(
            name="MyAgent",
            system_prompt="You are a helpful assistant.",
            model="gpt-4",
            temperature=0.7
        )

# Run the agent
agent = MyAgent()
result = await agent.run("What is the meaning of life?")
print(result)
```

### Creating a Custom Tool

```python
from heaven_base import BaseHeavenTool, ToolArgsSchema

class CalculatorToolArgsSchema(ToolArgsSchema):
    arguments = {
        'expression': {
            'type': 'str',
            'description': 'Mathematical expression to evaluate',
            'required': True
        }
    }

class CalculatorTool(BaseHeavenTool):
    name = "calculator"
    description = "Evaluates mathematical expressions"
    args_schema = CalculatorToolArgsSchema
    
    def _run(self, expression: str) -> str:
        try:
            result = eval(expression)
            return f"The result is: {result}"
        except Exception as e:
            return f"Error: {str(e)}"
```

## Core Components

- **BaseHeavenAgent**: Base class for all HEAVEN agents
- **BaseHeavenTool**: Base class for all HEAVEN tools
- **UnifiedChat**: Multi-provider LLM interface
- **HeavenEvent**: Standardized event format
- **History**: Advanced conversation history management

## Development Roadmap

HEAVEN Base is actively evolving with a clear roadmap to become a complete agent development toolkit:

### 🚀 Core Infrastructure (Current)
- ✅ **BaseHeavenAgent & BaseHeavenTool** - Foundation classes for agents and tools
- ✅ **Cross-Framework Support** - LangChain and Google ADK compatibility
- ✅ **HEAVEN Events** - Standardized event system for agent communication
- ✅ **Registry System** - Data storage and retrieval with cross-registry references
- ✅ **History Management** - Conversation tracking with ~/.heaven/ user directory

### 🛠️ Local Execution (In Progress)
- **Hermes Local Execution** - Non-containerized agent orchestration (replaces complex Docker setup)
- **Core Default Tools** - BashTool, NetworkEditTool, SafeCodeReaderTool out of the box
- **Simple Agent Runner** - run_agent() utility for immediate agent execution

### 🧠 LLM Integration Improvements
- **LiteLLM Integration** - Replace LangChain internals with LiteLLM for better provider support
- **Unified Message Formats** - Standardize all message handling to OpenAI format
- **Enhanced Provider Support** - Better error handling and feature parity across providers

### 🎯 Prompt Engineering System
- **Prompt Injection System** - Build input prompts from reusable blocks or freestyle strings
- **Template Management** - Organize and version prompt templates
- **Dynamic Composition** - Programmatically construct complex prompts

### 🔄 Context Engineering
- **Weave Operations** - Extract and reorganize conversation history
- **Inject Operations** - Add files, context, or arbitrary content to conversations
- **Context Compression** - Manage long conversations with smart truncation

### 🏗️ Workflow Orchestration
- **HeavenWorkflow Class** - Turn all components into LangGraph nodes
- **Lego-Style Building** - Compose agents, tools, and operations as reusable blocks
- **Visual Workflow Design** - Drag-and-drop agent workflow construction
- **Hierarchical Execution** - Nested workflows with state management

### 🎯 The Vision
HEAVEN Base aims to be the complete toolkit for agent development:
- **Install** → pip install heaven-base
- **Run** → hermes.run_agent(agent, prompt)
- **Compose** → Build prompts from blocks and inject context
- **Orchestrate** → Create complex workflows as LangGraph nodes
- **Scale** → Hierarchical agent networks with automatic state management

## Documentation

For full documentation, visit [https://heaven-base.readthedocs.io](https://heaven-base.readthedocs.io)

## License

MIT License - see LICENSE file for details.
