Un framework innovativo per sistemi cognitivi che unisce ragionamento simbolico e intelligenza artificiale

🚀 Quick Start •💡 Innovation •🏗️ Architecture •📄 Paper •📚 Docs •🧪 Type Checking •🎯 Threshold Learning •🔌 Plugins •📘 Onboarding DSL •🤝 Contributing

💡 What is ASPERA?

🚀 Why ASPERA?

🎯 Caratteristiche Principali

🚀 Quick Start

Prerequisiti

Installazione

# 1. Clone e setup ambientecd asperapython -m venv .venv# Windows PowerShell.venv\Scripts\Activate.ps1# Linux/Macsource .venv/bin/activate# 2. Installa dipendenzepip install -r requirements.txt# 3. Configura variabili d'ambientecp .env.example .env# Edita .env e aggiungi la tua GROQ_API_KEY

Uso CLI

# Parse un file .asperapython aspera_cli.py parse aspera/lang/examples/empathetic.aspera -o ast.json# Run con auto-detect (RACCOMANDATO - usa Groq se GROQ_API_KEY configurata)python aspera_cli.py run --aspera aspera/lang/examples/empathetic.aspera --signals examples/signals.json# Run forzando Groqpython aspera_cli.py run --aspera aspera/lang/examples/empathetic.aspera --signals examples/signals.json --mode groq# Run con mock LLM (solo per testing, no API key needed)python aspera_cli.py run --aspera aspera/lang/examples/empathetic.aspera --signals examples/signals.json --mode mock# Valida un ASTpython aspera_cli.py validate ast.json

🔥 NEW: Semantic Memory Plugin

# 1. Install ASTREA (semantic memory engine)git clone https://github.com/rthgit/Astrea.gitcd Astrea&& python interface/api/astrea_api_minimal.py&# 2. Install semantic memory plugincd ../asperapip install -e plugins/aspera-semantic-astrea# 3. Use in your agentpython examples/semantic_memory_demo.py

Plugin: installazione, discovery e uso (incluso Gemini)

# Installa plugin esterni (esempi)python -m pip install -e plugins/aspera-vector-weaviatepython -m pip install -e plugins/aspera-llm-openaipython -m pip install -e plugins/aspera-llm-geminipython -m pip install -e plugins/aspera-semantic-astrea# NEW!# Scopri e lista plugin disponibilipython aspera_cli.py plugins discoverpython aspera_cli.py plugins list

fromaspera.plugins.plugin_interfaceimportPluginManagerpm=PluginManager()pm.discover_plugins()llm=pm.get_plugin("openai_llm")orpm.get_plugin("gemini_llm")ifllm:llm.initialize({"model":"gpt-4o-mini","temperature":0.7})print(llm.generate_inference(context={},signals={},rules=["if a then b"]))vec=pm.get_plugin("weaviate_vector")ifvec:vec.initialize({"url":"http://localhost:8080","class_name":"AsperaVector"})vec.save("demo","hello")print("Loaded:",vec.load("demo"))

🔌 Plugins: installazione rapida

# Installa plugin pubblici (LLM OpenAI, Vector Weaviate)python -m pip install aspera-llm-openai aspera-vector-weaviate# Scopri e lista plugin disponibilipython aspera_cli.py plugins discoverpython aspera_cli.py plugins list

Esempio programmatico (PluginManager)

fromaspera.plugins.plugin_interfaceimportPluginManagerpm=PluginManager()pm.discover_plugins()# OpenAI LLM (richiede OPENAI_API_KEY nell'ambiente)llm=pm.get_plugin("openai_llm")ifllm:llm.initialize({"model":"gpt-4o-mini","temperature":0.7})res=llm.generate_inference(context={},signals={},rules=["if a then b"])print("LLM result:",res)# Weaviate Vector Storagevec=pm.get_plugin("weaviate_vector")ifvec:vec.initialize({"url":"http://localhost:8080","class_name":"AsperaVector"})vec.save("demo","hello")print("Loaded:",vec.load("demo"))# Semantic Memory (Coming Soon)# memory = pm.get_plugin("semantic_memory")  # Future feature

🧠 Semantic Memory (Coming Soon)

Planned Features

# Future API (planned)agent=AsperaAgent(memory="semantic")# Learn from past casesagent.learn_from_example(context="fever 39°C, cough, fatigue",decision="COVID test + isolation",outcome=0.95# Success rate)# Find similar cases for new patientsimilar=agent.find_similar_cases(context="fever 38.5°C, dry cough",top_k=5)# Use best match: 92% similarity, 95% success rate!

LSP (Language Server) Setup

# Avvio server LSP (stdin/stdout)python-m aspera.tools.lsp_server# oppure, se installato come scriptaspera-lsp

{"ltex.language":"it-IT","python.analysis.diagnosticMode":"openFilesOnly"}

Telemetry (OpenTelemetry)

$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"python aspera_cli.py run--aspera agents\enterprise\ecommerce_conversion_optimizer\conversion_optimizer.aspera--signals examples\signals_ecommerce.json--mode mock

Smoke test con Groq (tutti gli agent)

$code=@"import sys, os, jsonfrom pathlib import Pathsys.path.insert(0, os.path.abspath('.'))from aspera.sdk.client import create_engine, run_observationfiles = [str(p) for p in Path('agents').rglob('*.aspera')]report = []for f in files:    print('==> ', f)    eng = create_engine(f, use_mock_llm=False, auto_detect=True, enable_cache=True)    res = run_observation(eng, {}, {}, True)    report.append({'agent': f, 'actions': res['actions'], 'explanation': res['explanation']})with open('SMOKE_REPORT_GROQ.json','w', encoding='utf-8') as fp:    json.dump(report, fp, ensure_ascii=False, indent=2)print('Saved: SMOKE_REPORT_GROQ.json')"@$code| python-

Uso Docker

# Build e avvia tutti i servizidocker-compose up -d# Accedi all'UI# http://localhost:3000# API backend# http://localhost:8000/docs

Uso SDK

fromaspera.sdk.clientimportcreate_engine,run_observation# Carica un programma Asperaengine=create_engine("examples/empathetic.aspera")# Esegui osservazionesignals= {"coerenza_comportamento":0.7,"trasparenza":0.8}context= {"experiences": {"shared":5},"interaction_count":10}result=run_observation(engine,signals,context)print("Azioni:",result["actions"])print("Spiegazione:",result["explanation"])print("Trace:",result["audit_trace"])

📖 Struttura Progetto

aspera/├─ README.md├─ LICENSE├─ pyproject.toml├─ requirements.txt├─ .env.example├─ aspera_cli.py                    # CLI principale├─ aspera/│  ├─ __init__.py│  ├─ lang/                         # Definizione linguaggio│  │  ├─ grammar.aspera.bnf         # Grammatica BNF│  │  ├─ parser.py                  # Parser Python│  │  ├─ ast_schema.json            # JSON Schema AST│  │  └─ examples/                  # Esempi .aspera│  ├─ runtime/                      # Runtime cognitivo│  │  ├─ engine.py                  # CognitiveEngine│  │  ├─ symbolic.py                # Reasoner simbolico│  │  ├─ memory.py                  # Memoria episodica/semantica│  │  ├─ policy.py                  # Policy executor│  │  └─ llm_adapters/│  │      └─ groq_adapter.py        # Groq integration│  ├─ sdk/                          # SDK pubblico│  │  ├─ client.py│  │  └─ utils.py│  ├─ web/                          # Web stack│  │  ├─ api.py                     # FastAPI backend│  │  └─ ui/                        # React frontend│  └─ tests/                        # Test suite├─ docs/                            # Documentazione├─ training/                        # Training plan & scripts├─ datasets/                        # Dataset examples└─ infra/                           # Docker & CI

🧠 Linguaggio Aspera

Sintassi Base

// Definisci un concettoconcept "fiducia" {  definition: "credenza nella coerenza e buona volontà dell'altro";  signals: ["coerenza_comportamento", "trasparenza", "esperienze_condivise"];  baseline: 0.5;}// Associa concettiassociate "fiducia" -> "cooperazione" {  weight: 0.8;  bidirectional: true;}// Stato del sistemastate {  mood: "neutral";  energy_level: 0.7;  interaction_phase: "initial";}// Regola di inferenzainference "valuta_fiducia" {  when: signals.coerenza_comportamento > 0.6 and experiences.shared > 3;  then: increase concept:"fiducia" by 0.2;  confidence: 0.8;}// Intenzione strategicaintention "costruire_cooperazione" {  priority: high;  strategy:    - if concept:"fiducia" < 0.4 -> action: "aumenta_trasparenza"    - else -> action: "proponi_collaborazione_graduale";}// Template spiegazioneexplain {  format: "human";  template: "Credo che tu sia [interpretation] perché ho osservato [evidence].";}

🔧 Architettura Runtime

CognitiveEngine

Flusso di Esecuzione

observe(signals, context) → step() → decide() → explain()     ↓                         ↓         ↓          ↓  Context              Apply Rules   Select    Generate  Update               Update State  Actions   Explanation

🤖 Integrazione Groq

Configurazione

# .envGROQ_API_KEY=gsk_...ASPERA_ENV=developmentASPERA_DB_URL=sqlite:///aspera.db

Prompt Templates & Resilienza

📊 Training & Valutazione

🛡️ Sicurezza & Ethics

🧪 Testing

# Run test suitepytest aspera/tests/ -v# Con coveragepytest aspera/tests/ --cov=aspera --cov-report=html# Test specificipytest aspera/tests/test_parser.py -k"test_parse_concept"

📚 Documentazione Completa

🎬 Demo Video Script

🤝 Contributing

📄 License

👤 Author

🔗 Links