agentic-lang 0.2.0

package/examples/enterprise-example.agentic

@@ -0,0 +1,360 @@
+// Enterprise-Grade Application Example
+// Demonstrates: audit logging, compliance, security, observability
+
+@module("enterprise")
+
+// Audit logging for compliance
+@audit_trail(
+  retention: 7 * 365d,  // 7 years (regulatory requirement)
+  encryption: "AES-256",
+  immutable: true,
+  compliance: ["SOC2", "HIPAA", "GDPR"]
+)
+@confidence(0.96)
+@complete
+func processFinancialTransaction(
+  transaction: Transaction,
+  user: User
+) -> Result<Receipt, TransactionError> {
+  @audit.start({
+    action: "financial_transaction",
+    userId: user.id,
+    amount: transaction.amount,
+    timestamp: now(),
+    ipAddress: user.ipAddress,
+    userAgent: user.userAgent
+  })
+
+  // Validate user permissions
+  @requires_permission("financial.transactions.process")
+  if !user.hasPermission("financial.transactions.process") {
+    @audit.fail("insufficient_permissions", {
+      required: "financial.transactions.process",
+      userPermissions: user.permissions
+    })
+    return Err(TransactionError.INSUFFICIENT_PERMISSIONS)
+  }
+
+  // Validate transaction
+  @confidence(0.94)
+  validation = validateTransaction(transaction) match {
+    Ok(_) -> {},
+    Err(e) -> {
+      @audit.fail("validation_failed", { error: e, transaction })
+      return Err(TransactionError.VALIDATION_FAILED(e))
+    }
+  }
+
+  // Check for fraud
+  @confidence(0.89)
+  @llm_call(model: "fraud-detection-v2")
+  fraudCheck = detectFraud(transaction, user.history) match {
+    Ok(result) if result.score < 0.3 -> {},  // Low fraud risk
+    Ok(result) if result.score < 0.7 -> {
+      // Medium risk - require additional approval
+      @requires_approval(
+        approvers: ["fraud_team"],
+        timeout: 30m,
+        escalation: "security_team"
+      )
+      @audit.warning("fraud_check_flagged", { score: result.score })
+    },
+    Ok(result) -> {
+      // High risk - reject
+      @audit.fail("fraud_detected", {
+        score: result.score,
+        reasons: result.reasons
+      })
+      return Err(TransactionError.FRAUD_DETECTED)
+    },
+    Err(e) -> {
+      @audit.error("fraud_check_error", { error: e })
+      // Fail closed - require manual review
+      @escalate_to_human("Fraud detection system unavailable")
+    }
+  }
+
+  // Execute transaction with two-phase commit
+  @transaction(isolation: "serializable")
+  @confidence(0.93)
+  receipt = executeTransaction(transaction) match {
+    Ok(r) -> r,
+    Err(e) -> {
+      @audit.fail("transaction_execution_failed", { error: e })
+      return Err(TransactionError.EXECUTION_FAILED(e))
+    }
+  }
+
+  // Success audit
+  @audit.success({
+    receiptId: receipt.id,
+    amount: transaction.amount,
+    timestamp: now(),
+    processingTime: elapsed()
+  })
+
+  // GDPR: Record data processing
+  @gdpr_record({
+    dataSubject: user.id,
+    processing: "financial_transaction",
+    legalBasis: "contract",
+    purpose: "service_delivery",
+    retention: "7_years_regulatory"
+  })
+
+  return Ok(receipt)
+}
+
+// PII handling with encryption
+@pii_protection(
+  encrypt: ["ssn", "creditCard", "bankAccount"],
+  mask_in_logs: true,
+  requires_consent: true
+)
+@confidence(0.97)
+@complete
+func storeUserData(data: SensitiveUserData) -> Result<void, PrivacyError> {
+  // Check consent
+  if !data.user.hasConsent("data_storage") {
+    @audit.compliance_violation("missing_consent", {
+      userId: data.user.id,
+      dataTypes: ["pii", "financial"]
+    })
+    return Err(PrivacyError.MISSING_CONSENT)
+  }
+
+  // Encrypt PII automatically
+  encrypted = {
+    userId: data.user.id,
+    ssn: encrypt(data.ssn, key: envVar("PII_ENCRYPTION_KEY")),
+    creditCard: encrypt(data.creditCard, key: envVar("PII_ENCRYPTION_KEY")),
+    // Non-PII stored as-is
+    name: data.name,
+    email: data.email
+  }
+
+  database.sensitive_data.insert(encrypted) match {
+    Ok(_) -> {
+      @audit.pii_stored({
+        userId: data.user.id,
+        dataTypes: ["ssn", "creditCard"],
+        encrypted: true
+      })
+      return Ok(void)
+    },
+    Err(e) -> {
+      @audit.error("pii_storage_failed", { error: e })
+      return Err(PrivacyError.STORAGE_FAILED(e))
+    }
+  }
+}
+
+// GDPR right to erasure
+@gdpr_compliant(right: "erasure")
+@confidence(0.94)
+@complete
+@property("removes all user data")
+@property("cascades to related records")
+@property("generates deletion certificate")
+func deleteUserData(userId: string, reason: string) -> Result<DeletionCertificate, Error> {
+  @audit.start({
+    action: "gdpr_erasure",
+    userId: userId,
+    reason: reason,
+    requestedBy: getCurrentUser().id
+  })
+
+  // Find all user data across systems
+  @parallel(maxConcurrency: 5)
+  deletions = [
+    database.users.delete(userId),
+    database.transactions.deleteByUser(userId),
+    database.sensitive_data.deleteByUser(userId),
+    redis.deleteUserSessions(userId),
+    s3.deleteUserFiles(userId)
+  ]
+
+  // Verify all deletions succeeded
+  failures = deletions.filter(r => r.isErr())
+
+  if failures.length > 0 {
+    @audit.fail("incomplete_deletion", { failures })
+    return Err(Error.INCOMPLETE_DELETION {
+      failed: failures.length,
+      total: deletions.length
+    })
+  }
+
+  // Generate deletion certificate (legal requirement)
+  certificate = DeletionCertificate {
+    userId: userId,
+    deletedAt: now(),
+    requestReason: reason,
+    systemsAffected: ["database", "redis", "s3"],
+    verification: hash(deletions),
+    signature: sign(userId, now())
+  }
+
+  @audit.success({
+    userId: userId,
+    certificate: certificate.id
+  })
+
+  return Ok(certificate)
+}
+
+// Role-based access control
+@rbac(
+  resource: "financial_reports",
+  requiredRoles: ["accountant", "cfo", "auditor"]
+)
+@confidence(0.95)
+@complete
+func generateFinancialReport(
+  period: Period,
+  user: User
+) -> Result<FinancialReport, AccessError> {
+  // Automatic RBAC check before function executes
+
+  if !user.hasAnyRole(["accountant", "cfo", "auditor"]) {
+    @audit.access_denied({
+      userId: user.id,
+      resource: "financial_reports",
+      requiredRoles: ["accountant", "cfo", "auditor"],
+      userRoles: user.roles
+    })
+    return Err(AccessError.INSUFFICIENT_PRIVILEGES)
+  }
+
+  @audit.access_granted({
+    userId: user.id,
+    resource: "financial_reports",
+    userRole: user.roles.first()
+  })
+
+  report = compileFinancialData(period)
+
+  @audit.report_generated({
+    reportId: report.id,
+    period: period,
+    generatedBy: user.id,
+    dataPoints: report.data.length
+  })
+
+  return Ok(report)
+}
+
+// Distributed tracing for microservices
+@opentelemetry(
+  service: "enterprise-app",
+  exporter: "otlp",
+  endpoint: "https://telemetry.company.com"
+)
+@confidence(0.91)
+@effects(network, database, io, async)
+func orchestrateWorkflow(request: WorkflowRequest) -> Result<WorkflowOutput, Error> {
+  @span("validate_request", attributes: {
+    workflowType: request.type,
+    requestedBy: request.userId
+  })
+  validation = validateRequest(request)
+
+  @span("fetch_user_data", attributes: {
+    userId: request.userId
+  })
+  @retry(maxAttempts: 3, backoff: "exponential")
+  userData = database.users.find(request.userId)
+
+  @span("external_api_call", attributes: {
+    api: "partner-service",
+    timeout: "10s"
+  })
+  @circuit_breaker(threshold: 5, timeout: 60s)
+  externalData = partnerAPI.fetch(request.partnerId)
+
+  @span("llm_processing", attributes: {
+    model: "gpt-4.5",
+    max_tokens: 1000
+  })
+  @cost_tracked(userId: request.userId, feature: "workflow_processing")
+  processed = llm.process({
+    userData: userData,
+    externalData: externalData,
+    instructions: request.instructions
+  })
+
+  @span("store_results")
+  database.results.insert(processed)
+
+  return Ok(WorkflowOutput {
+    result: processed,
+    traceId: getCurrentTraceId()
+  })
+}
+
+// Security: Input sanitization
+@security_hardened(
+  injection_prevention: ["sql", "xss", "command"],
+  rate_limiting: { requests: 100, window: "1m" },
+  ip_whitelist: ["10.0.0.0/8", "192.168.0.0/16"]
+)
+@confidence(0.95)
+@complete
+func executeUserQuery(
+  query: UserQuery,
+  user: User
+) -> Result<QueryResult, SecurityError> {
+  // Automatic input sanitization
+  sanitized = SecurityGuard.sanitize(query) match {
+    Ok(q) -> q,
+    Err(e) -> {
+      @audit.security_violation({
+        type: "input_validation_failed",
+        userId: user.id,
+        violationType: e.violationType,
+        blocked: true
+      })
+      return Err(SecurityError.MALICIOUS_INPUT(e))
+    }
+  }
+
+  // Check rate limit
+  if RateLimiter.isExceeded(user.id) {
+    @audit.rate_limit_exceeded({ userId: user.id })
+    return Err(SecurityError.RATE_LIMIT_EXCEEDED)
+  }
+
+  // Execute with parameterized query (prevents SQL injection)
+  result = database.query(sanitized.sql, sanitized.params)
+
+  return Ok(result)
+}
+
+// Compliance reporting
+@compliance_report(
+  standard: "SOC2_TYPE2",
+  controls: ["access_control", "encryption", "audit_logging"]
+)
+@confidence(0.92)
+func generateSOC2Report(period: Period) -> SOC2Report {
+  auditLogs = collectAuditLogs(period)
+  accessLogs = collectAccessLogs(period)
+  securityIncidents = collectSecurityIncidents(period)
+
+  evidence = {
+    totalAuditEvents: auditLogs.length,
+    accessControlViolations: accessLogs.filter(l => l.denied).length,
+    securityIncidents: securityIncidents.length,
+    encryptionCoverage: calculateEncryptionCoverage(),
+    backupVerification: verifyBackups(period)
+  }
+
+  return SOC2Report {
+    period: period,
+    controls: evaluateControls(evidence),
+    evidence: evidence,
+    compliance: assessCompliance(evidence),
+    generatedAt: now(),
+    signature: signReport(evidence)
+  }
+}

package/examples/minimal.agentic

@@ -0,0 +1,3 @@
+func add(a: number, b: number) -> number {
+    return a
+}

package/examples/minimal.ts

@@ -0,0 +1,7 @@
+// Auto-generated from examples/minimal.agentic
+import { AgenticRuntime, Result, Ok, Err } from './runtime';
+
+function add(a: number, b: number): number {
+  return a;
+}
+

package/examples/ml-pipeline.agentic

@@ -0,0 +1,350 @@
+// Machine Learning Pipeline Example
+// Demonstrates: data processing, model inference, monitoring, cost optimization
+
+@module("ml_pipeline")
+
+// Data preprocessing with validation
+@confidence(0.91)
+@complete
+@needs(validator: DataValidator)
+@effects(io, state)
+@property("handles missing values")
+@property("normalizes numeric features")
+@property("encodes categorical features")
+func preprocessData(rawData: DataFrame) -> Result<ProcessedData, ValidationError> {
+  // Validate schema
+  @confidence(0.95)
+  validated = validator.validateSchema(rawData, schema: dataSchema) match {
+    Ok(data) -> data,
+    Err(errors) -> {
+      @context {
+        what_failed: "Schema validation",
+        errors: errors,
+        suggestions: ["Check data format", "Verify required columns present"]
+      }
+      return Err(ValidationError.SCHEMA_MISMATCH(errors))
+    }
+  }
+
+  // Handle missing values
+  @property("imputation preserves data distribution")
+  cleaned = validated
+    .fillna(strategy: "median", columns: numericColumns)
+    .fillna(strategy: "mode", columns: categoricalColumns)
+
+  // Normalize numeric features
+  @property("normalized values in range [0, 1]")
+  normalized = cleaned.normalize(columns: numericColumns, method: "min-max")
+
+  // Encode categorical features
+  @property("one-hot encoding preserves information")
+  encoded = normalized.oneHot(columns: categoricalColumns)
+
+  return Ok(ProcessedData {
+    data: encoded,
+    metadata: {
+      rowsProcessed: rawData.rows.length,
+      columnsProcessed: rawData.columns.length,
+      missingValuesHandled: countMissing(rawData),
+      encodingMaps: encoded.encodingMaps
+    }
+  })
+}
+
+// Model inference with cost tracking
+@cost_optimized(
+  cached_predictions: true,
+  batch_size: 32,
+  model_selection: "quality_vs_cost"
+)
+@confidence(0.89)
+@effects(llm_call, cost, async)
+func runInference(
+  input: ProcessedData,
+  userId: string
+) -> Result<Predictions, InferenceError> {
+  // Check cache first (zero cost)
+  cacheKey = hash(input)
+  cached = cache.get("predictions:${cacheKey}")
+
+  if cached {
+    @cost_saved(estimatedCost: 0.05)
+    @trace_decision("cache_hit", { cacheKey })
+    return Ok(cached)
+  }
+
+  // Check budget
+  budget = costRuntime.checkBudget(userId)
+
+  if budget.remaining < 0.10 {
+    return Err(InferenceError.BUDGET_EXCEEDED {
+      remaining: budget.remaining,
+      required: 0.10
+    })
+  }
+
+  // Select model based on input complexity
+  complexity = assessComplexity(input)
+
+  model = complexity match {
+    "simple" -> {
+      @llm_call(model: "gpt-4.5-turbo", max_tokens: 100)
+      @cost_tracked(userId: userId, feature: "inference_simple")
+      "gpt-4.5-turbo"
+    },
+    "moderate" -> {
+      @llm_call(model: "gpt-4.5", max_tokens: 500)
+      @cost_tracked(userId: userId, feature: "inference_moderate")
+      "gpt-4.5"
+    },
+    "complex" -> {
+      @llm_call(model: "o3", max_tokens: 2000)
+      @cost_tracked(userId: userId, feature: "inference_complex")
+      @requires_approval(if: budget.remaining < 1.00)
+      "o3"
+    }
+  }
+
+  // Run inference
+  @timeout(30s)
+  @retry(maxAttempts: 3, backoff: "exponential")
+  predictions = model.predict(input) match {
+    Ok(preds) -> preds,
+    Err(e) -> {
+      @context {
+        what_failed: "Model inference",
+        model: model,
+        inputSize: input.data.length,
+        suggestions: ["Check API status", "Verify input format", "Try simpler model"]
+      }
+      return Err(InferenceError.INFERENCE_FAILED(e))
+    }
+  }
+
+  // Cache successful predictions
+  cache.set("predictions:${cacheKey}", predictions, ttl: 1h)
+
+  // Monitor prediction confidence
+  @monitor_prediction_quality(
+    predictions: predictions,
+    threshold: 0.80,
+    alert_on_drift: true
+  )
+
+  return Ok(predictions)
+}
+
+// Batch inference for efficiency
+@batch_optimization(
+  maxBatchSize: 32,
+  maxWaitTime: 5s
+)
+@confidence(0.87)
+@effects(llm_call, cost, async)
+func batchInference(
+  inputs: ProcessedData[],
+  userId: string
+) -> Result<Predictions[], Error> {
+  // Batch requests to reduce per-request overhead
+  // 50-70% cost savings vs individual requests
+
+  batched = createBatches(inputs, size: 32)
+
+  @parallel(maxConcurrency: 4)
+  results = batched.map(batch => {
+    @llm_call(model: "gpt-4.5-turbo")
+    @cost_tracked(userId: userId, feature: "batch_inference")
+    return model.predictBatch(batch)
+  })
+
+  return Ok(results.flatten())
+}
+
+// Model monitoring and drift detection
+@healthcheck(interval: 5m)
+@confidence(0.88)
+@effects(database, io)
+func monitorModelPerformance() -> HealthStatus {
+  // Get recent predictions
+  predictions = database.predictions
+    .findRecent(limit: 1000)
+
+  // Calculate performance metrics
+  metrics = {
+    averageConfidence: mean(predictions.map(p => p.confidence)),
+    errorRate: predictions.filter(p => p.error).length / predictions.length,
+    latencyP95: percentile(predictions.map(p => p.latency), 0.95),
+    costPerPrediction: sum(predictions.map(p => p.cost)) / predictions.length
+  }
+
+  // Check for drift
+  if metrics.averageConfidence < 0.70 {
+    @alert("warning", {
+      message: "Model confidence declining",
+      averageConfidence: metrics.averageConfidence,
+      recommendation: "Consider retraining or model upgrade"
+    })
+    return HealthStatus.DEGRADED
+  }
+
+  if metrics.errorRate > 0.05 {
+    @alert("critical", {
+      message: "Error rate elevated",
+      errorRate: metrics.errorRate,
+      recommendation: "Investigate model or data issues"
+    })
+    return HealthStatus.FAILED
+  }
+
+  return HealthStatus.OK
+}
+
+// A/B testing for model comparison
+@ab_test(
+  variants: {
+    control: "gpt-4.5-turbo",
+    treatment: "fine-tuned-model-v2"
+  },
+  split: 0.5,  // 50/50 split
+  metric: "prediction_accuracy",
+  duration: 7d
+)
+@confidence(0.86)
+func compareModels(input: ProcessedData) -> Predictions {
+  // Automatically routes 50% to each model
+  // Tracks performance metrics
+  // Reports which model is better
+}
+
+// Feature engineering with confidence tracking
+@confidence(0.84)
+@partial("Basic features only, domain expertise needed for advanced")
+@uncertain("Optimal feature set not determined via experimentation")
+func engineerFeatures(rawData: DataFrame) -> EngineeeredFeatures {
+  features = {
+    // Numeric features
+    age: rawData.age,
+    income: log(rawData.income + 1),  // Log transform
+    creditScore: rawData.creditScore / 850,  // Normalize
+
+    // Categorical features
+    category: oneHot(rawData.category),
+    region: embedding(rawData.region),
+
+    // Interaction features
+    ageIncomeRatio: rawData.age / (rawData.income + 1),
+
+    // Time-based features
+    dayOfWeek: rawData.timestamp.dayOfWeek(),
+    hourOfDay: rawData.timestamp.hour()
+  }
+
+  @trace_features({
+    engineered: Object.keys(features).length,
+    original: rawData.columns.length,
+    transformation: "numeric_log_categorical_onehot"
+  })
+
+  return features
+}
+
+// Full ML pipeline orchestration
+@workflow(persistent: true, resumable: true)
+@confidence(0.85)
+@effects(io, database, llm_call, cost, async)
+func mlPipeline(
+  dataSource: DataSource,
+  userId: string
+) -> Result<MLPipelineOutput, PipelineError> {
+  // Step 1: Extract data
+  @checkpoint("data_extraction")
+  @retry(maxAttempts: 3)
+  rawData = dataSource.extract() match {
+    Ok(data) -> data,
+    Err(e) -> return Err(PipelineError.EXTRACTION_FAILED(e))
+  }
+
+  // Step 2: Preprocess
+  @checkpoint("preprocessing")
+  @confidence(0.91)
+  processed = preprocessData(rawData) match {
+    Ok(data) -> data,
+    Err(e) -> return Err(PipelineError.PREPROCESSING_FAILED(e))
+  }
+
+  // Step 3: Feature engineering
+  @checkpoint("feature_engineering")
+  @confidence(0.84)
+  features = engineerFeatures(processed.data)
+
+  // Step 4: Run inference
+  @checkpoint("inference")
+  @budget_limit(user_daily: 10.00, action: "throttle")
+  predictions = runInference(features, userId) match {
+    Ok(preds) -> preds,
+    Err(e) -> return Err(PipelineError.INFERENCE_FAILED(e))
+  }
+
+  // Step 5: Post-process and validate
+  @checkpoint("postprocessing")
+  @confidence(0.93)
+  @property("predictions in valid range")
+  validated = validatePredictions(predictions) match {
+    Ok(preds) -> preds,
+    Err(e) -> {
+      @alert("critical", "Prediction validation failed")
+      return Err(PipelineError.INVALID_PREDICTIONS(e))
+    }
+  }
+
+  // Step 6: Store results
+  @checkpoint("storage")
+  @transaction
+  database.predictions.insert({
+    userId: userId,
+    predictions: validated,
+    metadata: {
+      dataSource: dataSource.name,
+      timestamp: now(),
+      modelVersion: getCurrentModelVersion(),
+      cost: getTotalCost(userId)
+    }
+  })
+
+  @checkpoint("complete")
+
+  return Ok(MLPipelineOutput {
+    predictions: validated,
+    metadata: {
+      processingTime: elapsed(),
+      totalCost: getTotalCost(userId),
+      confidence: averageConfidence(validated)
+    }
+  })
+}
+
+// Monitoring dashboard data
+@confidence(0.92)
+@effects(database, io)
+func getMLMetrics(period: Period) -> MLMetricsDashboard {
+  return MLMetricsDashboard {
+    totalPredictions: database.predictions.count(period),
+    averageLatency: database.predictions.averageLatency(period),
+    errorRate: database.predictions.errorRate(period),
+    costMetrics: {
+      totalCost: costRuntime.getTotal(period),
+      costPerPrediction: costRuntime.getAverage(period),
+      costByModel: costRuntime.getByModel(period)
+    },
+    qualityMetrics: {
+      averageConfidence: database.predictions.averageConfidence(period),
+      mutationScore: getLatestMutationScore(),
+      verificationStatus: getVerificationStatus()
+    },
+    usageMetrics: {
+      topUsers: database.predictions.topUsers(period, limit: 10),
+      topFeatures: database.predictions.topFeatures(period, limit: 10),
+      peakHours: database.predictions.getHourlyDistribution(period)
+    }
+  }
+}