Lyrics - Super connection middleware about multi-agent and skills
Lyrics is a bash command proxy server designed for AI Agents to securely execute Agent Skills commands in containerized environments.
🎯 Why Lyrics?
Agent Skills need a secure bash environment to:
- Execute document processing (PDF, Excel, etc.)
- Run Python scripts and utilities
- Manage file system operations
- Maintain persistent shell sessions
🏗️ Architecture
┌─────────────────────────────────────┐
│ FastAPI Server │
│ • REST API (/api/v1/*) │
│ • Health checks │
├─────────────────────────────────────┤
│ Service Layer │
│ • Business logic │
│ • Thread pool management │
├─────────────────────────────────────┤
│ Command Processing │ File System │
│ • Security validation│ Path resolve │
│ • Shell sessions │ Access control│
├─────────────────────────────────────┤
│ Agent Skills (/skills) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ pdf │ │ xlsx │ │ Custom │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────┘
Key Components
- CommandParser: Validates bash commands with security checks
- CommandExecutor: Executes commands using persistent shell sessions
- PathResolver: Resolves skill/workspace paths
- PathValidator: Enforces security policies
🚀 Quick Start
Installation
Option 1: Install from PyPI (Recommended)
pip install ailyrics
Option 2: Install from Source (Development)
# Clone project
git clone https://github.com/your-org/lyrics.git
cd lyrics
# Install dependencies
uv sync
Start Server
# PyPI installation
python -m lyrics.server --host 0.0.0.0 --port 8870
# Source development
uv run python -m lyrics.server --host 0.0.0.0 --port 8870
# Docker mode (source only)
make docker-up
Verify Installation
curl http://localhost:8870/api/v1/health
# Returns: {"status": "healthy", "service": "lyrics", "api_version": "v1"}
📡 Core API
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/health |
Health check |
POST |
/api/v1/bash/execute |
Execute bash commands |
GET |
/api/v1/skills |
List all skills |
GET |
/api/v1/skills/{name} |
Get specific skill |
Execute Commands
curl -X POST http://localhost:8870/api/v1/bash/execute \
-H "Content-Type: application/json" \
-d '{"command": "ls -la /skills/public"}'
🔧 Agent Skills
Skill Structure
skill-name/
├── SKILL.md # YAML metadata + instructions (required)
├── scripts/ # Utility scripts (optional)
├── reference/ # Reference docs (optional)
└── data/ # Data files (optional)
YAML Frontmatter Format
---
name: pdf-processing
description: PDF toolkit for text extraction, form filling, etc.
license: MIT
---
# PDF Processing Guide
...detailed content...
Available Skills
- pdf: PDF document processing (text extraction, form filling)
- xlsx: Excel spreadsheet processing (formulas, data analysis)
⚠️ Security Constraints
The system blocks dangerous patterns for security:
- Shell operators:
;,&&,||,|,$,`,>,<,&❌ - Path traversal:
../../../etc/passwd❌ - Command injection attempts ❌
Alternative: Use Python
# ✅ Correct way
python3 -c "with open('file.txt', 'w') as f: f.write('content')"
🐍 Python Client Example
import asyncio
import httpx
async def main():
async with httpx.Client() as client:
# Health check
health = await client.get("http://localhost:8870/api/v1/health")
print(f"Service status: {health.json()['status']}")
# Execute command
result = await client.post(
"http://localhost:8870/api/v1/bash/execute",
json={"command": "echo 'Hello Lyrics!'"}
)
print(f"Output: {result.json()['stdout']}")
asyncio.run(main())
🛠️ Development
Project Structure
src/lyrics/
├── server.py # FastAPI main server
├── bash/ # Bash command processing
├── filesystem/ # File system operations
└── commands/ # Command handlers
Running Tests
# Full integration tests (recommended)
make docker-test
# Unit tests
make test
Code Quality
make fmt # Format code
make check # Check code quality
📊 Configuration
| Variable | Default | Description |
|---|---|---|
SKILLS_PATH |
/skills |
Skills directory |
WORKSPACE_PATH |
/workspace |
Working directory |
LOG_LEVEL |
INFO |
Log level |
HOST |
0.0.0.0 |
Server host |
PORT |
8870 |
Server port |
🤝 Contributing
- Fork the project
- Create feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Create Pull Request
📄 License
MIT License - see the LICENSE file for details.
Built for the Agent Skills ecosystem 🚀
Metadata
Release files for ailyrics 0.1.0
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 | Actions |
|---|---|---|---|---|
| ailyrics-0.1.0.tar.gz | 281.3 kB | Without provenance | Details for ailyrics-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ailyrics-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ailyrics-0.1.0-py3-none-any.whl |
Total release size: 321.7 kB
Release files / ailyrics-0.1.0.tar.gz
| Download URL | ailyrics-0.1.0.tar.gz |
|---|---|
| Size | 281.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
25254f32492dc5e47ee8639173eb58580372139777cf0c85b5322fcbc1065ee3
|
|
BLAKE2b-256 checksum How to use checksums |
7511b568e042bb4a027d9c97786de8e447b73bab6929cb7c053b328a2c6d6ed6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ailyrics-0.1.0-py3-none-any.whl
| Download URL | ailyrics-0.1.0-py3-none-any.whl |
|---|---|
| Size | 40.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e822483b9bde50075e198d5eb789fcb1df88efaebfe98ea1b4b3a79d844f166e
|
|
BLAKE2b-256 checksum How to use checksums |
69f020eef76c61e92afe1c809ec6ebed51b93ddaa5eca328baa24062238d3110
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ailyrics 0.1.0
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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.