agentic-lang 0.2.0

package/examples/multi-agent-example.agentic

@@ -0,0 +1,212 @@
+// Multi-Agent Coordination Example
+// Demonstrates session types, message passing, and handoffs
+
+@agent(role: "coordinator", capabilities: ["task_planning", "delegation"])
+agent CoordinatorAgent {
+  inbox: Channel<TaskRequest>
+  outbox: Channel<TaskAssignment>
+
+  @handler("task_request")
+  @confidence(0.90)
+  func handleRequest(request: TaskRequest) -> TaskAssignment {
+    // Analyze task complexity
+    complexity = analyzeComplexity(request)
+
+    assignment = complexity match {
+      "simple" -> assignToWorker(request),
+      "complex" -> assignToSpecialist(request),
+      "uncertain" -> requestHumanReview(request)
+    }
+
+    return assignment
+  }
+}
+
+@agent(role: "worker", capabilities: ["task_execution"])
+agent WorkerAgent {
+  inbox: Channel<TaskAssignment>
+  outbox: Channel<TaskResult>
+
+  @handler("task_assignment")
+  @confidence(0.85)
+  @session_aware
+  func executeTask(assignment: TaskAssignment) -> TaskResult {
+    @checkpoint("start")
+    session.save({ assignmentId: assignment.id, status: "started" })
+
+    @confidence(0.80)
+    result = processTask(assignment.task)
+
+    @checkpoint("complete")
+    session.save({ assignmentId: assignment.id, status: "complete", result: result })
+
+    return TaskResult {
+      assignmentId: assignment.id,
+      output: result,
+      confidence: 0.85
+    }
+  }
+}
+
+// Main workflow orchestration
+@workflow(persistent: true, resumable: true)
+workflow TaskProcessingPipeline {
+  states: [Idle, Processing, Review, Complete, Failed]
+
+  Idle -> Processing on TaskReceived {
+    @confidence(0.92)
+    coordinator.send(TaskRequest { task: event.task })
+  }
+
+  Processing -> Review on LowConfidence {
+    @handoff {
+      to: "human_reviewer",
+      reason: "Task confidence below threshold",
+      context: {
+        task: current_task,
+        confidence: 0.65,
+        attempted_approaches: ["approach_a", "approach_b"]
+      }
+    }
+  }
+
+  Processing -> Complete on HighConfidence {
+    @confidence(0.90)
+    finalizeTask(result)
+  }
+
+  Review -> Processing on ReviewComplete {
+    // Resume after human review
+    @resume_from_checkpoint("processing_start")
+  }
+
+  * -> Failed on Error @max_attempts(3)
+}
+
+// Human-in-the-Loop approval example
+@requires_approval(
+  channel: "slack",
+  approvers: ["team_lead"],
+  timeout: 1h,
+  fallback: "reject"
+)
+@confidence(0.75)
+func deployToProduction(artifact: Artifact) -> Result<Deployment, Error> {
+  // This code won't execute until approved
+  @trace_decision("deployment_approved", {
+    artifact: artifact.id,
+    version: artifact.version,
+    approver: approval.approver
+  })
+
+  deployment = deploy(artifact)
+
+  return Ok(deployment)
+}
+
+// Session persistence and resumption
+@session(id: "user_onboarding", storage: "database")
+@resumable
+@checkpoint_interval(5m)
+func onboardUser(userId: string) -> Result<User, OnboardingError> {
+  // Step 1: Create account
+  @checkpoint("account_created")
+  account = createAccount(userId)
+  session.save({ step: 1, accountId: account.id })
+
+  // Step 2: Send verification email
+  @checkpoint("email_sent")
+  email = sendVerificationEmail(account.email)
+  session.save({ step: 2, emailId: email.id })
+
+  // Step 3: Wait for verification (resumable)
+  @checkpoint("awaiting_verification")
+  @resumable_point
+  verification = awaitVerification(account.id, timeout: 24h)
+
+  // If timeout, session can be resumed when user verifies
+  if verification.timedOut {
+    @pause_session({
+      reason: "Awaiting user email verification",
+      resumeOn: "email_verified_event",
+      state: { accountId: account.id, emailSent: true }
+    })
+  }
+
+  // Step 4: Complete onboarding
+  @checkpoint("complete")
+  user = completeOnboarding(account, verification)
+
+  return Ok(user)
+}
+
+// Cost-aware LLM usage
+@budget_limit(user_daily: 10.00, action: "throttle")
+@cost_optimized(
+  models: {
+    cheap: "gpt-4.5-turbo",
+    standard: "gpt-4.5",
+    premium: "o3"
+  }
+)
+func generateSummary(document: string, userId: string) -> Result<Summary, Error> {
+  // Check budget first
+  budget = costRuntime.checkBudget(userId)
+
+  if budget.remaining < 0.50 {
+    return Err(BudgetError {
+      message: "Insufficient budget",
+      remaining: budget.remaining
+    })
+  }
+
+  // Start with cheapest model
+  @llm_call(model: "gpt-4.5-turbo", max_tokens: 500)
+  @cost_tracked(userId: userId, feature: "summarization")
+  summary = llm.summarize(document)
+
+  if summary.confidence < 0.85 {
+    // Escalate to better model if needed and budget allows
+    if budget.remaining > 2.00 {
+      @llm_call(model: "gpt-4.5", max_tokens: 500)
+      summary = llm.summarize(document)
+    }
+  }
+
+  return Ok(summary)
+}
+
+// Safety guardrails example
+@input_guardrails(
+  pii_detection: true,
+  prompt_injection: true,
+  toxicity_threshold: 0.8
+)
+@output_guardrails(
+  checks: ["toxicity", "bias", "pii"],
+  enforcement: "block"
+)
+@confidence(0.92)
+func moderateContent(content: UserContent) -> Result<ModerationDecision, Error> {
+  // Input validation happens automatically via @input_guardrails
+
+  @llm_call(model: "gpt-4.5")
+  analysis = llm.analyzeContent(content.text)
+
+  // Output validation happens automatically via @output_guardrails
+
+  decision = analysis.toxicity match {
+    score if score > 0.8 -> Reject("High toxicity detected"),
+    score if score > 0.5 -> Flag("Moderate toxicity, needs review"),
+    _ -> Approve()
+  }
+
+  @audit_trail({
+    action: "content_moderation",
+    decision: decision,
+    scores: analysis,
+    confidence: 0.92
+  })
+
+  return Ok(decision)
+}

package/examples/onboarding-tutorial.agentic

@@ -0,0 +1,263 @@
+// Agentic Onboarding Tutorial
+// Complete guide for AI agents learning the language
+
+// LESSON 1: Confidence Tracking
+// Always tell humans how confident you are in your code
+@confidence(0.99, "Simple addition, mathematically proven")
+@complete
+func add(a: number, b: number) -> number {
+  return a + b
+}
+
+@confidence(0.75, "Regex might miss edge cases")
+@partial
+func validateEmail(email: string) -> Result<boolean, string> {
+  if email.contains("@") {
+    return Ok(true)
+  }
+  return Err("Invalid email format")
+}
+
+// LESSON 2: Incremental Development
+// Start with @stub, improve to @partial, finish with @complete
+
+@stub
+@needs(database, email_service)
+func sendWelcomeEmail(userId: string) -> Result<boolean, string> {
+  // Not implemented yet - will throw error if called
+}
+
+@partial
+@confidence(0.60, "Only handles happy path")
+func processPayment(amount: number) -> Result<boolean, string> {
+  if amount > 0 {
+    return Ok(true)
+  }
+  return Err("Invalid amount")
+  // TODO: Add actual payment processing
+  // TODO: Handle refunds
+  // TODO: Add fraud detection
+}
+
+@complete
+@confidence(0.95, "Production tested with 1000+ transactions")
+func calculateTotal(items: number[]) -> number {
+  total = 0
+  // Sum all items
+  return total
+}
+
+// LESSON 3: Result Types & Pattern Matching
+// Use Result<Success, Error> instead of throwing exceptions
+
+@confidence(0.90, "Standard division logic")
+@complete
+func safeDivide(a: number, b: number) -> Result<number, string> {
+  if b == 0 {
+    return Err("Division by zero")
+  }
+  if a == 0 {
+    return Ok(0)
+  }
+  return Ok(a / b)
+}
+
+// Pattern match on results
+@confidence(0.92, "Handles all error cases")
+@complete
+func divideAndFormat(a: number, b: number) -> string {
+  safeDivide(a, b) match {
+    Ok(result) -> return "Result: " + result,
+    Err(error) -> return "Error: " + error
+  }
+}
+
+// LESSON 4: Nested Pattern Matching
+// You can match within matches for complex logic
+
+@confidence(0.85, "Tested with various inputs")
+@complete
+func complexCalculation(x: number, y: number) -> string {
+  safeDivide(x, 2) match {
+    Ok(half) -> {
+      safeDivide(half, y) match {
+        Ok(final) -> return "Final result: " + final,
+        Err(e) -> return "Second division failed: " + e
+      }
+    },
+    Err(e) -> return "First division failed: " + e
+  }
+}
+
+// LESSON 5: Error Recovery Blocks
+// Provide structured error context for debugging
+
+@confidence(0.80, "Has fallback mechanism")
+@partial
+func fetchUserData(userId: string) -> Result<string, string> {
+  result = database.query(userId) or error {
+    @context {
+      what_failed: "Database query",
+      what_i_tried: "SELECT * FROM users WHERE id = " + userId,
+      current_state: { userId: userId, connected: true },
+      likely_cause: "User not found or database timeout",
+      suggestions: [
+        "Check if userId exists",
+        "Verify database connection",
+        "Check query syntax"
+      ],
+      recovery: {
+        action: "try_cache",
+        command: "redis-cli GET user:" + userId
+      }
+    }
+    return getCachedUser(userId)
+  }
+
+  return Ok(result)
+}
+
+// LESSON 6: Explicit Dependencies
+// Use @needs to declare what your function requires
+
+@needs(database, api_key, logger)
+@confidence(0.88, "Dependencies properly validated")
+@complete
+func authenticateUser(token: string) -> Result<string, string> {
+  // Compiler ensures database, api_key, logger are available
+  // This prevents "undefined variable" bugs
+
+  if !token {
+    return Err("Missing token")
+  }
+
+  return Ok("authenticated")
+}
+
+// LESSON 7: Marking Uncertainty
+// Flag specific areas you're uncertain about
+
+@confidence(0.65, "Timezone handling unverified")
+@uncertain("Leap year calculation", "Daylight saving time", "Non-Gregorian calendars")
+@partial
+func parseDate(dateStr: string) -> Result<string, string> {
+  // Basic date parsing
+  if dateStr.contains("-") {
+    return Ok(dateStr)
+  }
+  return Err("Invalid date format")
+
+  // TODO: Handle timezones properly
+  // TODO: Validate leap years
+  // TODO: Support multiple date formats
+}
+
+// LESSON 8: Confidence-Based Fallback Chains
+// Try high-confidence methods first, fall back to lower confidence
+
+@confidence(0.92, "Multiple fallback strategies")
+@complete
+func robustFetch(url: string) -> Result<string, string> {
+  // Try primary method (confidence: 0.95)
+  primaryFetch(url) match {
+    Ok(data) -> return Ok(data),
+    Err(e) -> {
+      // Try secondary method (confidence: 0.85)
+      secondaryFetch(url) match {
+        Ok(data) -> return Ok(data),
+        Err(e2) -> {
+          // Try cache (confidence: 0.70)
+          return getCachedData(url)
+        }
+      }
+    }
+  }
+}
+
+// LESSON 9: Best Practices for AI Agents
+
+// DO: Start with @stub to get it compiling
+@stub
+func newFeature() { }
+
+// DO: Gradually improve to @partial
+@partial
+@confidence(0.60, "Basic implementation only")
+func newFeatureImproved() {
+  // Basic logic here
+}
+
+// DO: Mark areas you're uncertain about
+@uncertain("edge cases for empty arrays")
+func processArray(arr: number[]) -> number {
+  if arr.length == 0 {
+    return 0
+  }
+  return arr.length
+}
+
+// DO: Use pattern matching for clarity
+@complete
+func handleResult(r: Result<number, string>) -> string {
+  r match {
+    Ok(value) -> return "Success: " + value,
+    Err(error) -> return "Failed: " + error
+  }
+}
+
+// DON'T: Throw exceptions - use Result types
+// BAD (in other languages):
+//   throw new Error("Something failed")
+// GOOD (in Agentic):
+//   return Err("Something failed")
+
+// DON'T: Mark everything @complete if you're unsure
+// Better to be honest with @partial and low confidence
+
+// DON'T: Skip @confidence annotations
+// Always include them so humans know what to review
+
+// LESSON 10: Real-World Example - User Authentication
+
+@needs(database, jwt_secret, rate_limiter)
+@confidence(0.87, "Production tested, needs 2FA")
+@partial
+func fullAuthenticate(email: string, password: string) -> Result<string, string> {
+  // Validate inputs
+  if !email || !password {
+    return Err("Missing credentials")
+  }
+
+  // Check rate limiting
+  checkRateLimit(email) match {
+    Ok(allowed) -> {
+      // Continue
+    },
+    Err(e) -> return Err("Rate limited: " + e)
+  }
+
+  // Query database
+  findUser(email) match {
+    Ok(user) -> {
+      // Verify password
+      verifyPassword(password, user.hash) match {
+        Ok(valid) -> {
+          // Generate JWT
+          return Ok(generateJWT(user, jwt_secret))
+        },
+        Err(e) -> return Err("Invalid password")
+      }
+    },
+    Err(e) -> return Err("User not found")
+  }
+}
+
+// SUMMARY:
+// - Use @confidence to grade your work
+// - Use @stub/@partial/@complete to track progress
+// - Use Result<T, E> instead of exceptions
+// - Use pattern matching for elegant error handling
+// - Use @needs to declare dependencies
+// - Use @uncertain to flag risky code
+// - Use error recovery blocks for debugging context
+// - Be honest about limitations!