Joule-Style AI Skill Prototype
mrsalinshahi/Joule-Style-Prototype
API REST para skills de IA com contexto, JWT e enriquecimento Claude
Ver no GitHubProtótipo de assistente IA estilo SAP Joule que expõe habilidades de inteligência de processos via API REST segura e context-aware. Construído com FastAPI, Pydantic v2 e Anthropic Claude, inclui autenticação JWT, escoping de permissões e narração de resultados enriquecida por LLM.
Instalação
npx convez-ai mrsalinshahi/Joule-Style-Prototype1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar assistentes IA de processos empresariais escaláveis
- Executar análises de inteligência (gargalos, KPIs, sumários executivos)
- Manter contexto de conversas multi-turno com session store
Veredito

Projeto sólido e bem-documentado que demonstra padrões profissionais de integração com Claude (streaming, context awareness, permission scoping). Excelente referência para quem quer construir assistentes IA empresariais com controle fino de acesso.
README
A tradução para o português deste README ainda está na fila.
Joule-Style AI Skill Prototype
A portfolio project that mimics how SAP's Joule AI assistant exposes process intelligence skills through a secure, context-aware REST API. Built with FastAPI, Pydantic v2, and the Anthropic Claude API.
What It Does
- Skill execution — invoke named actions against business process data (bottleneck analysis, KPI retrieval, executive summaries)
- LLM enrichment — each skill result is optionally narrated by Claude, which also proposes next steps
- Context retention — a session store keeps the last 10 conversation turns per
session_id, so follow-up questions are context-aware - Token auth + permission scoping — JWT Bearer tokens carry scopes (
read,admin); skills declare which scope they require
Project Structure
joule-style-prototype/
├── app/
│ ├── main.py # FastAPI app, routers, skill registry
│ ├── skills/
│ │ ├── base_skill.py # Abstract base class every skill must implement
│ │ └── process_skill.py # Process Intelligence skill (3 mock processes)
│ ├── auth/
│ │ └── token_auth.py # JWT creation, verification, scope guard
│ ├── models/
│ │ └── schemas.py # Pydantic v2 request/response models
│ └── core/
│ └── response_flow.py # Session store + async Claude enrichment
├── tests/
│ └── test_skills.py # 21 pytest tests
├── docs/
│ ├── configuration_guide.md
│ └── handover_guide.md
└── requirements.txt
Setup
Prerequisites
- Python 3.11+ (project was developed and tested on Python 3.14)
- uv (recommended) or pip
1. Clone and enter the project
git clone <repo-url>
cd joule-style-prototype
2. Create a virtual environment and install dependencies
With uv (recommended):
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
With pip:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
3. Set environment variables
# Required for LLM enrichment. The API will work without it — responses
# are returned without the Claude narrative layer.
export ANTHROPIC_API_KEY="sk-ant-..."
# Optional: override the JWT signing secret (strongly recommended in production)
export JWT_SECRET_KEY="your-random-256-bit-secret"
4. Run the server
uvicorn app.main:app --reload --port 8000
Visit http://localhost:8000/docs for the interactive OpenAPI UI.
API Reference
Base URL
http://localhost:8000
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /health | None | Liveness probe |
POST | /api/v1/auth/token | None | Generate a Bearer token |
GET | /api/v1/skill/list | Bearer | List skills and their schemas |
POST | /api/v1/skill/execute | Bearer | Execute a skill action |
Curl Examples
Health check
curl http://localhost:8000/health
{"status": "ok", "skills_registered": 1}
Get a token — admin user (scopes: read + admin)
curl -s -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin123"}' | python3 -m json.tool
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"scopes": ["read", "admin"],
"expires_in": 3600
}
Get a token — analyst user (scope: read only)
curl -s -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "analyst", "password": "analyst123"}' | python3 -m json.tool
List available skills
TOKEN="<paste token here>"
curl -s http://localhost:8000/api/v1/skill/list \
-H "Authorization: Bearer $TOKEN" | python3 -m json.tool
Execute: summarize a process
curl -s -X POST http://localhost:8000/api/v1/skill/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_name": "process_intelligence",
"action": "summarize_process",
"parameters": {"process_name": "order_to_cash"},
"session_id": "demo-session-1"
}' | python3 -m json.tool
Response:
{
"skill_name": "process_intelligence",
"action": "summarize_process",
"session_id": "demo-session-1",
"result": {
"process_name": "order_to_cash",
"display_name": "Order-to-Cash",
"summary": "Order-to-Cash is operating at moderate efficiency...",
"health_score": 0.72,
"avg_cycle_time_days": 14.3,
"sla_breach_rate": 0.08,
"findings": ["Health score: 72%", "..."],
"narrative": "Order-to-Cash shows moderate efficiency at 72% health..."
},
"confidence": 0.85,
"suggested_next_actions": [
{
"action": "analyze_bottleneck",
"description": "Drill into bottlenecks identified in the summary.",
"parameters": {}
}
],
"context_turns_used": 0,
"llm_enhanced": true
}
Execute: get KPIs
curl -s -X POST http://localhost:8000/api/v1/skill/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_name": "process_intelligence",
"action": "get_kpi",
"parameters": {"process_name": "procure_to_pay", "metric": "quality"},
"session_id": "demo-session-1"
}' | python3 -m json.tool
Execute: analyze bottlenecks
curl -s -X POST http://localhost:8000/api/v1/skill/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_name": "process_intelligence",
"action": "analyze_bottleneck",
"parameters": {"process_name": "hire_to_retire"},
"session_id": "demo-session-1"
}' | python3 -m json.tool
Context-aware follow-up (same session_id)
After running the summarize call above, the LLM receives the prior turn as context:
curl -s -X POST http://localhost:8000/api/v1/skill/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_name": "process_intelligence",
"action": "analyze_bottleneck",
"parameters": {"process_name": "order_to_cash"},
"session_id": "demo-session-1"
}' | python3 -m json.tool
Notice context_turns_used is now 1 — the system remembered the previous summarize call.
Error cases
Wrong password:
curl -s -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "wrong"}'
# → 401 Unauthorized
Missing required parameter:
curl -s -X POST http://localhost:8000/api/v1/skill/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_name": "process_intelligence",
"action": "summarize_process",
"parameters": {},
"session_id": "s1"
}'
# → 400 Bad Request: Missing required parameters: ['process_name']
Skill not found:
# → 404 Not Found
Running Tests
# All tests
pytest tests/ -v
# Single class
pytest tests/test_skills.py::TestAuth -v
# With coverage
pip install pytest-cov
pytest tests/ --cov=app --cov-report=term-missing
Available Test Users
| Username | Password | Scopes |
|---|---|---|
admin | admin123 | read, admin |
analyst | analyst123 | read |
Available Processes (mock data)
| Process Key | Display Name |
|---|---|
order_to_cash | Order-to-Cash |
procure_to_pay | Procure-to-Pay |
hire_to_retire | Hire-to-Retire |
Environment Variables
| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY | (empty) | Claude API key. If absent, LLM enrichment is skipped gracefully. |
JWT_SECRET_KEY | dev-secret-CHANGE-... | HMAC secret for JWT signing. Change before any deployment. |
Further Reading
- docs/configuration_guide.md — how to add a new skill
- docs/handover_guide.md — architecture decisions and known limitations