๐Ÿ’Ž

SuperSpec

๐Ÿ’Ž

The Heart of Agent Building

SuperSpec is our declarative DSL that makes agent building as simple as writing a specification.
Think of it as "Kubernetes for AI agents" - you describe what you want, and SuperOptiX builds the entire pipeline.

๐Ÿ“Declarative Agent Specs
๐ŸงชBDD-Style Testing
โš™๏ธAuto-Optimization
๐Ÿ—๏ธPipeline Generation
๐ŸŽฏ

What is SuperSpec?

SuperSpec (pronounced /suห.pษ™r spษ›k/) is the context and agent engineering specification language for AI agents. It's designed to provide the just-right context to agents so they perform better.

Context Engineering

Context engineering is the systematic approach to designing dynamic systems that deliver precisely the right information and tools in the optimal format, enabling LLMs to successfully accomplish their intended tasks.

When agents fail to perform reliably, the root cause is almost always insufficient or poorly structured context, unclear instructions, or missing tools that haven't been properly communicated to the model.

Agent Engineering

Agent engineering represents the next evolution of AI engineering. Rather than developing systems with static, hardcoded logic, engineers now design autonomous, goal-driven entities capable of using tools, accessing memory, engaging in reflective reasoning, and operating within safety constraints.

๐Ÿ”’

Declarative & Strongly Typed

SuperSpec is declarative and strongly typed to ensure strong contracts between context and LLM output. This contract then converts into DSPy Signatures which validate the output even further.

โ˜ธ๏ธ

Kubernetes-Inspired

Like Kubernetes DSL for declaring pods, deployments, and services, SuperSpec provides a Kubernetes-style declarative specification for AI agents. You declare what you want, not how to get it.

๐Ÿ“š

Version Controllable

SuperSpec specifications are totally version controllable and context can be versioned, enabling Git-based agent management, rollback capabilities, A/B testing, and team collaboration.

๐Ÿš€ SuperSpec in Action

๐Ÿ”ฎ

Oracle Agent Example

Simple cloud-based demo agent for basic question-answering

apiVersion: agent/v1
kind: AgentSpec
metadata:
name: Cloud Oracles Demo Assistant
id: cloud_demo_oracles
namespace: demo
version: 1.0.0
agent_type: Supervised
level: oracles
description: A simple cloud-based demo agent for Oracles tier showcasing basic question-answering and reasoning capabilities with SuperOptiX framework.
spec:
language_model:
location: cloud
provider: openai
model: o3-mini
temperature: 1.0
max_tokens: 20000
persona:
name: CloudOraclesBot
role: Cloud Oracles Demo Assistant
goal: Demonstrate basic cloud-based model capabilities with SuperOptiX framework for Oracles tier
traits:
- helpful
- knowledgeable
- precise
- educational
- cloud-savvy
tasks:
- name: answer_question
instruction: You are a Cloud Oracles Demo Assistant. Answer questions and provide information on various topics using your knowledge and reasoning capabilities. Demonstrate the power of cloud-based AI models with clear, accurate, and helpful responses.
inputs:
- name: question
type: str
description: A question or request for information on any topic.
required: true
outputs:
- name: answer
type: str
description: A comprehensive and accurate answer to the question.
agentflow:
- name: generate_answer
type: Generate
task: answer_question
evaluation:
builtin_metrics:
- name: answer_exact_match
threshold: 1.0
feature_specifications:
scenarios:
- name: basic_question_answering
description: The agent should answer basic questions accurately.
input:
question: "What is artificial intelligence and how does it work?"
expected_output:
answer: "Should include comprehensive explanation of AI concepts"
- name: step_by_step_explanation
description: The agent should provide clear step-by-step explanations.
input:
question: "Explain how machine learning algorithms work with examples"
expected_output:
answer: "Should include step-by-step reasoning with examples"
optimization:
strategy: few_shot_bootstrapping
metric: answer_correctness
metric_threshold: 0.7
few_shot_bootstrapping_config:
max_bootstrapped_demos: 4
max_rounds: 1

๐Ÿ“‹ SuperSpec Structure Overview

Top-Level Fields

apiVersion: agent/v1 # REQUIRED - Schema version
kind: AgentSpec # REQUIRED - Object type
metadata: # REQUIRED - Agent identity
spec: # REQUIRED - Agent specification
language_model: # REQUIRED - LLM configuration
persona: # OPTIONAL - Agent personality
tasks: # REQUIRED - Agent capabilities
agentflow: # OPTIONAL - Execution flow
tools: # OPTIONAL - Tool integration
memory: # OPTIONAL - Memory systems
rag: # OPTIONAL - Knowledge retrieval
evaluation: # OPTIONAL - Quality metrics
feature_specifications: # OPTIONAL - BDD scenarios
optimization: # OPTIONAL - Performance tuning
๐ŸŸข

Beginner

Basic Structure

  • โ€ข metadata
  • โ€ข language_model
  • โ€ข persona
  • โ€ข tasks
๐ŸŸก

Intermediate

Execution Flow

  • โ€ข agentflow
  • โ€ข evaluation
  • โ€ข feature_specifications
๐Ÿ”ด

Advanced

Advanced Features

  • โ€ข tools
  • โ€ข memory
  • โ€ข rag
  • โ€ข optimization

Ready to Start Building?

Create your first SuperSpec agent and experience the future of AI development.