convez.ai
SkillIntegração & APIsAvançado
mrsalinshahi

Joule-Style AI Skill Prototype

mrsalinshahi/Joule-Style-Prototype

API REST para skills de IA com contexto, JWT e enriquecimento Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Protó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-Prototype

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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

MethodPathAuthDescription
GET/healthNoneLiveness probe
POST/api/v1/auth/tokenNoneGenerate a Bearer token
GET/api/v1/skill/listBearerList skills and their schemas
POST/api/v1/skill/executeBearerExecute 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

UsernamePasswordScopes
adminadmin123read, admin
analystanalyst123read

Available Processes (mock data)

Process KeyDisplay Name
order_to_cashOrder-to-Cash
procure_to_payProcure-to-Pay
hire_to_retireHire-to-Retire

Environment Variables

VariableDefaultDescription
ANTHROPIC_API_KEY(empty)Claude API key. If absent, LLM enrichment is skipped gracefully.
JWT_SECRET_KEYdev-secret-CHANGE-...HMAC secret for JWT signing. Change before any deployment.

Further Reading

Ver o original no GitHub

Bom para

Relacionados