HEAVEN Base Framework
⭐ 0 stars • 🕑 Updated 2026-07-09
📦 Auto-published from the monorepo • CHANGELOG • sancovp/heaven-framework
Hierarchical, Embodied, Autonomously Validating Evolution Network
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
pip install heaven-framework
Toolbox MCP
Claude Code
"heaven-framework-toolbox": {
"type": "stdio",
"command": "python",
"args": [
"-m",
"heaven_base.mcps.toolbox_server"
],
"env": {
"HEAVEN_DATA_DIR": "YOUR_HEAVEN_DATA_DIR", # /tmp/heaven_data recommended
"OPENAI_API_KEY": "sk-YOUR_OPENAI_API_KEY"
}
}
SDK
Quick Start
Creating a Simple Agent
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
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-framework
- 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
License
MIT License - see LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for heaven-framework 0.1.36
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| heaven_framework-0.1.36.tar.gz | 1.5 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| heaven_framework-0.1.36-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.0 MB
Release files / heaven_framework-0.1.36.tar.gz
| Download URL | heaven_framework-0.1.36.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2b9a734e28a943c02057fcddda944b649279ccb4d6e824855ea643fe362fd9c7
|
|
BLAKE2b-256 checksum How to use checksums |
8a18dc5b8ffd937b4241df06428c88cd077f93d626772eacc176f50b39d0fc45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / heaven_framework-0.1.36-py3-none-any.whl
| Download URL | heaven_framework-0.1.36-py3-none-any.whl |
|---|---|
| Size | 513.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
657a890180f28098d8c7d286d6a05a3752546851b084cc8c4d2785f8aceb237c
|
|
BLAKE2b-256 checksum How to use checksums |
561032ad4a2f9c95fdc38cb9046621dd3e8b09218c7350b1518c7fa17d2508cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for heaven-framework 0.1.36
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
