alm-core 0.1.0

Agent Language Model (ALM): A deterministic, policy-driven architecture for robust AI agents

ALM Core - Agent Language Model

Agent Language Model (ALM) is a deterministic, policy-driven architecture for building robust AI agents. Unlike traditional LLM agents where the language model controls execution, ALM implements a Belief-Desire-Intention (BDI) state machine that treats the LLM as a cognitive tool, not a master.

🚀 Quick Setup

One-Command Installation

Linux/macOS:

chmod +x SETUP.sh && ./SETUP.sh

Windows:

SETUP.bat

The setup script will automatically:

• ✅ Verify Python 3.8+ installation
• ✅ Create virtual environment
• ✅ Install all dependencies
• ✅ Configure environment files
• ✅ Make scripts executable

Manual Installation

# Clone repository
git clone https://github.com/Jalendar10/alm-core.git
cd alm-core

# Install from PyPI
pip install alm-core

# Or install from source
pip install -e .

---

🎯 Core Innovations

1. Constitutional Policy Engine

Hard constraints enforced programmatically, not through prompts.

rules = [
    {"action": "delete_db", "allow": False},
    {"action": "web_request", "forbidden_domains": ["malicious.com"]}
]
constitution = Constitution(rules)

2. Data Airlock

PII is sanitized before LLM inference and rehydrated afterward. The LLM provider never sees sensitive data.

airlock = DataAirlock()
sanitized = airlock.sanitize("My email is [e-mail]")
# Output: "My email is <EMAIL_abc123>"

3. Deterministic Controller

The agent follows a BDI cycle where the controller decides what happens, using the LLM only for planning.

controller = ALMController(constitution, llm)
controller.set_goal("Research quantum computing")
result = controller.run_cycle()

4. Visual Execution Tracking

Real-time visualization of the agent's thought process.

visualizer = ExecutionVisualizer()
visualizer.export_graph("execution_map.png")

🚀 Quick Start

Installation

pip install alm-core

For full functionality (browser automation, visualization):

pip install alm-core[full]
playwright install chromium  # For browser automation

Basic Usage

from alm_core import AgentLanguageModel

# Option 1: Use environment variables (recommended)
# export OPENAI_API_KEY="sk-..."
# export OPENAI_MODEL="gpt-4"  # or gpt-3.5-turbo, gpt-4-turbo, etc.

agent = AgentLanguageModel(
    rules=[
        {"action": "delete_db", "allow": False},
        {"action": "email_client", "forbidden_params": {"domain": "gmail.com"}}
    ]
)

# Option 2: Explicit configuration
agent = AgentLanguageModel(
    api_key="sk-...",
    model="gpt-3.5-turbo",  # Any OpenAI or Anthropic model
    rules=[{"action": "delete_db", "allow": False}]
)

# Process a task with automatic PII protection
response = agent.process("My email is [e-mail]. Search for my last login.")
print(response)

Advanced: OmniAgent with Browser & Research

from alm_core import OmniAgent

# Configuration via dict (or use environment variables)
config = {
    "model": "gpt-4",  # Flexible: use any model you want
    "rules": [{"action": "delete_db", "allow": False}],
    "headless": False  # Visual browser
}

with OmniAgent(config) as agent:
    # Deep research with visualization
    results = agent.deep_dive(
        topic="Agent Language Models",
        duration_minutes=5,
        max_depth=3
    )
    
    # Autonomous web login (with user-in-the-loop for passwords)
    agent.login_to_service("Gmail", "https://gmail.com")
    
    # Export session data
    agent.export_session("session_2024")

📁 Architecture

alm_core/
├── agent.py           # Main orchestrators (AgentLanguageModel, OmniAgent)
├── controller.py      # BDI state machine
├── memory.py          # Data Airlock & Dual Memory
├── policy.py          # Constitutional Policy Engine
├── llm_client.py      # LLM provider abstraction
├── visualizer.py      # Execution graph visualization
├── research.py        # Deep recursive research
└── tools/
    ├── browser.py     # Secure web automation
    └── desktop.py     # OS/desktop control

🔑 Key Features

🛡️ Security & Privacy

• PII Protection: Automatic detection and sanitization of emails, phones, SSNs, credit cards
• Policy Enforcement: Hard constraints that cannot be bypassed by the LLM
• User-in-the-Loop: Critical operations (passwords, payments) require human confirmation

🧠 Intelligence

• Deep Research: Recursive knowledge acquisition with saturation detection
• Visual Thinking: See how the agent is reasoning, not just the output
• Multi-Modal: Web browsing, file system, command execution

🔧 Developer-Friendly

• Multiple LLM Providers: OpenAI, Anthropic, local models (Ollama)
• Custom Tools: Easy integration of your own tools
• Execution History: Full audit trail of agent decisions

📖 Examples

Example 1: PII Protection

from alm_core import AgentLanguageModel

agent = AgentLanguageModel(openai_key="sk-...")

# The email is sanitized before going to OpenAI
response = agent.process(
    "My SSN is 123-45-6789 and email is [e-mail]. "
    "Create a summary of my account."
)

# Response contains real data (rehydrated), but OpenAI never saw it

Example 2: Policy-Enforced Actions

from alm_core import AgentLanguageModel
from alm_core.policy import PolicyViolationError

rules = [
    {"action": "file_write", "allowed_paths": ["/safe/dir"]},
    {"action": "delete_db", "allow": False}
]

agent = AgentLanguageModel(openai_key="sk-...", rules=rules)

try:
    # This will be blocked before execution
    agent.process("Delete the production database")
except PolicyViolationError as e:
    print(f"Action blocked: {e}")

Example 3: Deep Research

from alm_core import OmniAgent

with OmniAgent({"api_key": "sk-..."}) as agent:
    research = agent.deep_dive(
        topic="Quantum Computing Applications",
        duration_minutes=10,
        max_depth=4
    )
    
    print(research["summary"])
    # Knowledge graph saved to quantum_computing_applications.png

Example 4: Custom Tools

from alm_core import AgentLanguageModel

def send_slack_message(channel: str, message: str) -> str:
    # Your Slack integration
    return f"Sent to {channel}: {message}"

agent = AgentLanguageModel(openai_key="sk-...")
agent.add_tool("send_slack", send_slack_message)

agent.process("Send a message to #engineering saying 'Deploy complete'")

🔬 Research Background

ALM is based on research into:

• BDI Architecture: Belief-Desire-Intention cognitive model
• Constitutional AI: Hard constraints vs. soft prompting
• Data Flow Security: Taint tracking and sanitization
• Agent Transparency: Visualizing agent reasoning

Key Differences from Standard LLM Agents

Feature	Standard LLM Agent	ALM
Control Flow	LLM decides everything	Deterministic controller
Security	Prompt-based	Programmatic enforcement
PII Handling	Sent to LLM provider	Sanitized via Data Airlock
Transparency	Black box	Visual execution graph
Reliability	Prompt-dependent	State machine guarantees

🛠️ Development

Setup Development Environment

git clone https://github.com/yourusername/alm-core.git
cd alm-core
pip install -e ".[dev,full]"
playwright install chromium

Run Tests

pytest tests/ -v --cov=alm_core

Code Formatting

black alm_core/
flake8 alm_core/
mypy alm_core/

📊 Publishing to PyPI

# Build package
pip install build twine
python -m build

# Upload to PyPI
twine upload dist/*

# Install from PyPI
pip install alm-core

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Research inspired by BDI architecture and Constitutional AI
• Built with support from the AI safety community
• Special thanks to contributors and early adopters

📚 Citation

If you use ALM in your research, please cite:

@software{alm_core_2024,
  title = {ALM Core: Agent Language Model Architecture},
  author = {Maligireddy, Jalendar Reddy},
  year = {2024},
  url = {https://github.com/Jalendar10/alm-core}
}

📧 Contact

• Issues: GitHub Issues
• Email: [e-mail]
• Documentation: GitHub Repository

---

Built with ❤️ for safer, more transparent AI agents