# OCLAWMA

**O**pen**C**law **W**orkflow **M**anagement **A**gent

[![CI](https://github.com/openclaw/oclawma/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/oclawma/actions)
[![PyPI](https://img.shields.io/pypi/v/oclawma.svg)](https://pypi.org/project/oclawma/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A powerful, extensible AI agent framework with lazy-loaded skills, multi-provider LLM support, and intelligent context management.

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI
pip install oclawma

# Or install with development dependencies
pip install oclawma[dev]
```

### Start an Interactive Session

```bash
# Start with default local model (requires Ollama)
oclawma run

# Use a specific model
oclawma run --model llama3.2:latest

# Use Kimi cloud provider
export KIMI_API_KEY="your-api-key"
oclawma run --provider kimi --model k2.5

# Auto provider (local with cloud fallback)
oclawma run --provider auto
```

### First Conversation

```
╔══════════════════════════════════════════════════════════╗
║           🦀 Welcome to OCLAWMA v0.2.0                   ║
║       OpenClaw Workflow Management Agent                 ║
╚══════════════════════════════════════════════════════════╝

You: Hello! Can you help me with my project?

Assistant: Hello! I'd be happy to help you with your project. What would you like to work on?

You: exit
```

## ✨ Features

- **🧠 Multi-Provider LLM Support**: Ollama (local), Kimi (cloud), and auto-fallback
- **🔧 Lazy-Loaded Skills**: Skills load on-demand for fast startup
- **📦 Pip-Installable Skills**: Distribute skills via PyPI
- **💬 Interactive Sessions**: REPL-style conversation with tool calling
- **📊 Context Budget**: Token usage tracking with proactive management
- **🗜️ Context Compression**: Automatic summarization when approaching limits
- **🛡️ Safety Controls**: Configurable safety levels for tool execution
- **🔌 Extensible**: Easy to add new providers, tools, and skills

## 📖 Documentation

- [Installation Guide](docs/installation.md) - Detailed installation instructions
- [Configuration Reference](docs/configuration.md) - Environment variables and settings
- [Skill Development Guide](docs/skill-development.md) - Create your own skills
- [Architecture Overview](docs/architecture.md) - System design and components
- [API Reference](docs/api-reference.md) - Python API documentation

## 🛠️ Built-in Tools

| Tool | Description |
|------|-------------|
| `read` | Read file contents |
| `write` | Write content to files |
| `exec` | Execute shell commands |

## 🧩 Available Skills

Install additional skills via pip:

```bash
# Docker skill
pip install oclawma-skill-docker

# Kubernetes skill
pip install oclawma-skill-kubernetes

# GitHub skill
pip install oclawma-skill-github
```

## 💻 Interactive Commands

During a session, use these commands:

| Command | Description |
|---------|-------------|
| `exit`, `quit` | End the session |
| `/clear` | Clear conversation history |
| `/compact` | Summarize conversation to save tokens |
| `/status` | Show session status and token budget |
| `/help` | Show available commands |

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        CLI Layer                            │
│                    (Click commands)                         │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐    ┌─────────────────┐    ┌──────────────┐
│   Session    │    │    Providers    │    │    Skills    │
│   Runner     │◄──►│  (Ollama/Kimi)  │    │   Registry   │
└──────────────┘    └─────────────────┘    └──────────────┘
        │                                           │
        ▼                                           ▼
┌──────────────┐                         ┌─────────────────┐
│Context Budget│                         │  Lazy Loading   │
│  Tracker     │                         │   System        │
└──────────────┘                         └─────────────────┘
```

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- [Documentation](https://openclaw.github.io/oclawma)
- [PyPI](https://pypi.org/project/oclawma)
- [Issues](https://github.com/openclaw/oclawma/issues)
- [Discussions](https://github.com/openclaw/oclawma/discussions)
