sparkit 0.1.3

A lightweight runtime SDK for executing Python sparkit scripts

📦 sparkit Runtime SDK

Um runtime leve para execução de scripts Python sparkit com:

• 🧠 Geração automática de schema
• 🖥️ CLI profissional (flags, help, validação)
• 🔄 Compatível com stdin/stdout (modo pipeline)
• ⚡ Execução de funções ou classes
• Uso de @Input / @Output / @Run decoradores

---

🚀 Instalação

git clone https://github.com/kelwp/sparkit
cd sparkit

Ou apenas copie a pasta sparkit para a raiz do seu projeto.

---

⚡ Uso rápido

🔹 Exemplo com classe

from sparkitSDK import sparkit

class SampleMonitor(NodeBase):
    ip: str
    device_id: str | None = None

    outputs_def = {
        'meta': {'type': dict[str, str]},
        'main': {'type': dict[str, int]}
    }

    def run(self):
        self.outputs.set_data("main", {"msg": "OK"})
        sparkit.set_stdout({"teste": 1})
        self.outputs.set_data("meta", {"status": 1})

if __name__ == "__main__":
    sparkit.run(SampleMonitor)

---

🔹 Executando via CLI

python script.py --ip 192.168.0.1

---

🔹 Saída

{
  "stdout": {
    "status": "ok",
    "ip": "192.168.0.1"
  },
  "stderr": null
}

---

🧠 Modos de entrada

1. Flags (CLI moderna)

python script.py --ip 123

---

2. JSON inline

python script.py --input '{"ip":"123"}'

---

3. Arquivo JSON

python script.py --input-file data.json

---

4. stdin (modo pipeline)

echo '{"ip":"123"}' | python script.py

👉 Ideal para integração com automações e orquestradores.

---

📖 Help automático

python script.py --help

Exemplo:

sparkit Script CLI

Inputs:
  --ip (string, required)

Other options:
  --input '<json>'
  --input-file <file>
  --schema
  --help

Outputs:
  status (string)
  ip (string)

---

🧬 Schema automático

python script.py --schema

Saída:

{
  "schema": {
    "inputs": [{ "name": "ip", "type": "string", "required": true }],
    "outputs": [
      { "name": "status", "type": "string" },
      { "name": "ip", "type": "string" }
    ]
  }
}

---

⚙️ Tipos suportados

Tipo	Exemplo CLI	Resultado
string	--name John	"John"
number	--age 25	25
boolean	--active true	true
array	--tags '[1,2,3]'	[1,2,3]
json	--data '{"a":1}'	{ "a":1 }

---

🧪 Execução com função

from runtime import sparkitRuntime

def handler(ip: str):
    return {"status": "ok", "ip": ip}

if __name__ == "__main__":
    sparkitRuntime().run(handler)

---

🔁 Estrutura de saída

Todo script retorna:

{
  "stdout": {...},
  "stderr": null
}

Ou em caso de erro:

{
  "stdout": null,
  "stderr": {
    "type": "ValueError",
    "message": "Missing required input: ip",
    "traceback": "..."
  }
}

---

🧩 Integração com sparkit

Esse runtime foi projetado para funcionar diretamente em pipelines:

• Recebe JSON via stdin
• Retorna JSON estruturado
• Possui schema introspectivo

👉 Ideal para:

• automações
• workflows
• agentes
• execução remota

---

🏗️ Arquitetura

• sparkitRuntime
  • parsing CLI
  • leitura de inputs
  • execução
  • geração de schema
  • tratamento de erro

---

🔒 Validações

• Campos obrigatórios (required)
• Tipagem automática
• Erros estruturados
• Argumentos desconhecidos são rejeitados

---

💡 Filosofia

Esse SDK segue 3 princípios:

1. Zero boilerplate
2. CLI primeiro
3. Compatível com pipelines

---

🚀 Roadmap

• Autocomplete (bash/zsh)
• Logs coloridos
• Plugins
• Execução assíncrona
• Cache de execução

---

🤝 Contribuição

Pull requests são bem-vindos!

---

📄 Licença

MIT

---

Examples

Os exemplos estão em examples/ e demonstram tanto o estilo baseado em classe (com decoradores) quanto o estilo procedural.

• examples/sample_class_dec.py — Exemplo OO com @Input, @Output, @Run, @MainOut, @Out.
• examples/sample_class.py — Exemplo OO simples.
• examples/sample_imp.py — Exemplo procedural com funções.

Instalação das dependências dos exemplos:

pip install -r examples/requirements.txt

O que temos agora (novidades)

• Geração de schema para funções e classes.
• Inferência estática de campos retornados por dicionários (mostra fields em stdout e saídas customizadas quando detectado).
• Suporte total para decoradores @Input aplicado em classes e métodos @Out/@MainOut.
• CLI: --schema, --help, --input, --input-file.

Versão atual do pacote: 0.1.2.