Ananke Quickstart Guide

Get started with constraint-driven code generation in 10-15 minutes.

Last Updated: March 2026 Status: Current with CLaSH 5-domain algebra, 14 languages, FIM, domain fusion, 617 tests

What You'll Learn

In this guide, you'll:

Build Ananke from source (3 minutes)
Run your first constraint extraction (2 minutes)
Try semantic analysis with Claude (3 minutes, optional)
Understand the full pipeline (5 minutes)

Total Time: 10-15 minutes

Before You Start

What is Ananke?

Ananke ensures AI-generated code always satisfies your requirements. Instead of hoping language models follow your patterns, you define explicit constraints and Ananke enforces them at the token level during generation.

The Key Insight: Code that violates your constraints simply cannot be generated.

How It Works

Your Code/Tests/Docs
        ↓
   Extract Constraints (Clew)      ← What patterns does your code follow?
        ↓
   Compile Constraints (Braid)     ← Optimize for fast validation
        ↓
   Generate Code (Maze)            ← Enforce constraints token-by-token
        ↓
   Validated Output                ← Guaranteed to satisfy all constraints

What You Need

Required:

Zig 0.15.2 or later (download here)
5-10 minutes

Optional (for advanced features):

Claude API key (for semantic analysis)
Modal account (for code generation)

Check your Zig version:

zig version
# Should print: 0.15.2 or higher

Step 1: Build Ananke (3 minutes)

Clone and build the project:

# Clone the repository
git clone https://github.com/ananke-ai/ananke.git
cd ananke

# Build everything (includes all examples)
zig build

# Verify the build
./zig-out/bin/ananke --version
# Expected: ananke 0.2.1

What just happened?

Zig compiled the constraint extraction engine (Clew)
Built the constraint compiler (Braid)
Created the orchestration layer (Maze, in Rust)
Compiled all working examples

Step 2: Extract Your First Constraints (2 minutes)

Let's see Ananke in action with Example 01 - simple constraint extraction.

Run the Example

cd examples/01-simple-extraction
zig build run

Expected Output:

=== Ananke Example 01: Simple Constraint Extraction ===

Analyzing file: sample.ts
File size: 1247 bytes

Extracting constraints (without Claude)...

Found 12 constraints:

Constraint 1: user_create_function_signature
  Kind: syntactic
  Severity: error
  Description: Function createUser must accept UserInput and return Promise<User>
  Source: static_analysis
  Confidence: 1.00

Constraint 2: required_password_field
  Kind: type_safety
  Severity: error
  Description: Password field must be present and non-empty
  Source: static_analysis
  Confidence: 0.95

[... more constraints ...]

=== Summary by Kind ===
  syntactic: 4
  type_safety: 5
  security: 2
  semantic: 1

What Did You Just Do?

Analyzed TypeScript code without any external services
Extracted 12 constraints including:
- Function signatures (syntactic)
- Type requirements (type safety)
- Security patterns (security)
Got confidence scores for each constraint
All in under 100ms - pure static analysis

Try It on Your Own Code

# Back to ananke root
cd ../..

# Extract constraints from any code file
./zig-out/bin/ananke extract /path/to/your/code.ts

Step 3: Add Semantic Analysis with Claude (3 minutes, optional)

Static analysis finds structural patterns. Claude finds business rules and implicit constraints.

Set Up Claude (if you have an API key)

# Set your API key
export ANTHROPIC_API_KEY='your-key-here'

# Run Example 02
cd examples/02-claude-analysis
zig build run

Expected Output:

=== Ananke Example 02: Claude-Enhanced Analysis ===

Analyzing file: sample.py
File size: 2341 bytes

=== Phase 1: Static Analysis (No LLM) ===

Static analysis found 8 constraints

[... structural constraints ...]

=== Phase 2: With Claude Analysis ===

Claude API key found - semantic analysis enabled

Semantic constraints Claude would extract:

1. Business Rule: High-Value Payment Threshold
   - Payments over $10,000 require additional verification
   - Confidence: 0.95 (explicitly stated in comment)
   - Kind: operational

2. Security Rule: Rate Limiting Policy
   - 3 failed attempts within 24 hours triggers rate limit
   - Confidence: 0.90 (implied by code + comment)
   - Kind: security

3. Compliance Rule: PCI-DSS
   - Never log full card numbers
   - Confidence: 1.0 (explicit comment)
   - Kind: security

[... more semantic constraints ...]

What's the Difference?

Static Analysis (no LLM):

Fast (under 100ms)
Finds function signatures, types, patterns
Deterministic and free
Limited to what's explicitly in the code structure

Semantic Analysis (with Claude):

Slower (around 2 seconds)
Finds business rules, implicit constraints, intent
Understands comments and documentation
Costs per request (~$0.01-0.05)

Best Practice: Use both! Static analysis for structure, Claude for semantics.

Step 4: See the Full Picture (5 minutes)

Let's understand how all the pieces fit together with Example 05.

cd examples/05-mixed-mode
zig build run

This example shows how to combine:

Extracted constraints (from Clew)
JSON configuration (simple policies)
Ariadne DSL (complex business rules)

Expected Output:

=== Ananke Example 05: Mixed-Mode Constraints ===

=== Phase 1: Extract from Code ===
Extracted 15 constraints from sample.ts
  - Function signatures and types
  - Error handling patterns
  - Null safety checks

=== Phase 2: Load JSON Config ===
Loaded constraints.json (342 bytes)
  - Environment variable requirements
  - Error logging format
  - Test coverage minimum

=== Phase 3: Load Ariadne DSL ===
Loaded custom.ariadne (587 bytes)
  - Database retry logic requirement
  - Standard API response format
  - Payment amount validation

=== Phase 4: Merge All Sources ===
Total constraints from all sources:
  Extracted (Clew):     ~15 constraints
  JSON Config:          3 constraints
  Ariadne DSL:          3 constraints
  ─────────────────────────────────
  Total:                ~21 constraints

Understanding the Layers

Think of constraints as layers of protection:

Layer 1 - Foundation (Extracted):
  │ Function signatures
  │ Type definitions
  │ Error handling patterns
  └─> Discovered automatically

Layer 2 - Configuration (JSON):
  │ Environment requirements
  │ Logging standards
  │ Quality gates
  └─> Organizational policies

Layer 3 - Domain Rules (Ariadne):
  │ Retry logic
  │ Response formats
  │ Payment validation
  └─> Business logic

All layers compose into a single set of constraints that enforce everything at once.

What's Next?

You've just learned the foundation of Ananke! Here's what to explore next:

For Learning

Read the Architecture (docs/ARCHITECTURE.md)
- Deep dive into how each component works
- Understanding the constraint types
- Performance characteristics
Try the Ariadne DSL (Example 03)
```
cd examples/03-ariadne-dsl
zig build run
```
- Learn the constraint definition language
- Write type-safe constraint definitions
Read the User Guide (docs/USER_GUIDE.md)
- Comprehensive coverage of all features
- Advanced usage patterns
- Troubleshooting guide

For Building

Deploy the Inference Service
- modal deploy maze/modal_inference/inference.py
- OpenAI-compatible endpoint with constraint_spec extension
- Requires Modal account (GPU infrastructure)

Try Fill-in-the-Middle (FIM)

ananke generate --fim --prefix "fn add(" --suffix ") -> i32 {" --language zig

IDE-quality constrained infill
See docs/FIM_GUIDE.md

Integrate with Your Project

# Use as a library
# Add to your build.zig.zon:
.ananke = .{
    .url = "https://github.com/ananke-ai/ananke/archive/refs/tags/v0.2.1.tar.gz",
    .hash = "...",
},

For Production

Set Up CI/CD Integration
- Validate code in pull requests
- Enforce constraints before merge
- See USER_GUIDE.md "Common Tasks" section
Build Constraint Libraries
- Define organization-wide policies
- Share constraints across teams
- Version control your standards

Common Questions

Q: Do I need Claude API for basic use?

No. Static analysis (Clew) works great without any external services. You get:

Function signatures and types
Error handling patterns
Security patterns
Architectural constraints

Claude is optional for semantic understanding of business rules.

Q: Can I generate code yet?

Yes! The complete system is production-ready:

Extract constraints (Clew) ✓ PRODUCTION READY
Compile constraints (Braid) ✓ PRODUCTION READY
Define constraints (Ariadne) ✓ Parsing complete (type checking deferred to v0.2)
Generate code (Maze) ✓ PRODUCTION READY with Modal inference service

The full pipeline is deployed and tested. See examples/04-full-pipeline for end-to-end usage. Code generation requires Modal service configuration (see /modal_inference/).

Q: How fast is constraint extraction?

Very fast:

Static analysis: 50-100ms
With Claude: ~2 seconds
Constraint compilation: 30-50ms

Fast enough for interactive use and CI/CD.

Q: What languages are supported?

Tier 1 — Full tree-sitter AST (9 languages, 0.95 confidence):

TypeScript (typescript, ts), JavaScript (javascript, js)
Python (python, py), Rust (rust, rs), Go (go), Zig (zig)
C (c), C++ (cpp, c++), Java (java)

Tier 2 — tree-sitter + patterns (5 languages, 0.85 confidence):

Kotlin (kotlin, kt), C# (csharp, cs)
Ruby (ruby, rb), PHP (php), Swift (swift)

All 14 languages support constraint extraction, CLaSH domain compilation, and type analysis.

Q: How accurate is constraint extraction?

Static analysis: 100% accurate for structural patterns (function signatures, types, etc.)

Semantic analysis with Claude: 85-95% confidence on business rules (with confidence scores provided)

Q: What about false positives?

Each constraint includes:

Confidence score (0.0 to 1.0)
Source (static analysis vs. LLM)
Severity (error, warning, info)

You can filter by confidence threshold to reduce false positives.

Troubleshooting

Build Fails

# Clean and rebuild
rm -rf zig-cache/ zig-out/
zig build

# Check Zig version
zig version  # Must be 0.15.2+

Examples Don't Run

# Make sure you're in the example directory
cd examples/01-simple-extraction

# Build the example
zig build

# Run it
zig build run

Claude API Issues

# Verify your key is set
echo $ANTHROPIC_API_KEY

# If empty, set it:
export ANTHROPIC_API_KEY='your-key-here'

# Test with Example 02
cd examples/02-claude-analysis
zig build run

"Zig not found"

Install Zig from https://ziglang.org/download/

On macOS:

brew install zig

On Linux:

# Download from ziglang.org, then:
tar xf zig-*.tar.xz
export PATH=$PWD/zig-*:$PATH

Key Takeaways

After this quickstart, you should understand:

Ananke enforces constraints at the token level during code generation
Three ways to define constraints:
- Extract from code (automatic)
- JSON configuration (simple)
- Ariadne DSL (expressive)
Two analysis modes:
- Static analysis (fast, free, structural)
- Semantic analysis (slower, costs, understands intent)
Current status:
- Constraint extraction: Production-ready ✓ (14 languages, tree-sitter AST)
- Constraint compilation: Production-ready ✓ (CLaSH 5-domain algebra, domain fusion)
- Code generation: Production-ready ✓ (sglang/Modal, FIM support)
- 617 tests (473 Zig + 144 Rust), zero memory leaks

The Full Pipeline (Now Available)

The complete end-to-end workflow is ready:

# 1. Extract constraints from your codebase
ananke extract ./src --output constraints.json

# 2. Compile constraints
ananke compile constraints.json --output compiled.cir

# 3. Generate code with constraints
ananke generate "Add user authentication endpoint" \
    --constraints compiled.cir \
    --output auth.ts

# 4. Validate (automatic during generation)
# Output is guaranteed to satisfy all constraints!

See Example 04 (examples/04-full-pipeline) for the complete working implementation.

Troubleshooting

Common Issues

Build Errors

Problem: error: tree-sitter library not found

Solution:

# macOS
brew install tree-sitter

# Ubuntu/Debian
sudo apt-get install libtree-sitter-dev

# Arch Linux
sudo pacman -S tree-sitter

# Verify
tree-sitter --version

Problem: error: Zig version 0.15.0 or later required

Solution:

# Download latest Zig from https://ziglang.org/download/
# Or use version manager:
zigup 0.15.2

Problem: error: no field named 'root_source_file'

Solution: You're using old Zig syntax. Update to Zig 0.15.0+ which uses:

// Old (Zig 0.13)
.root_source_file = .{ .path = "src/main.zig" }

// New (Zig 0.15+)
.root_source_file = b.path("src/main.zig")

Memory Errors

Problem: Memory leak warnings when running CLI commands

Solution: This has been fixed in recent versions. Update to latest main branch:

cd ananke
git pull origin main
zig build

If you still see leaks, they might be from:

Using outdated binaries (rebuild with zig build)
Custom code not calling deinit() properly
Report as bug if persistent after rebuild

Problem: Out of memory when processing large files

Solution:

# Increase file size limit (default: 10MB)
# Not currently configurable - split large files into smaller chunks

# Or process files individually:
for file in src/**/*.ts; do
    ananke extract "$file" -o "constraints_$(basename $file .ts).json"
done

Runtime Errors

Problem: error: UnsupportedLanguage

Solution: Check supported languages:

Tier 1 (tree-sitter AST): TypeScript, JavaScript, Python, Rust, Go, Zig, C, C++, Java
Tier 2 (tree-sitter + patterns): Kotlin, C#, Ruby, PHP, Swift

All 14 languages are fully supported with constraint extraction and CLaSH domain compilation.

Problem: error: FileNotFound or error: AccessDenied

Solution:

# Check file exists
ls -la path/to/file

# Check permissions
chmod +r path/to/file

# Use absolute paths if relative paths fail
ananke extract /absolute/path/to/file.ts

Problem: No constraints extracted from valid code

Solution:

# Verify language detection
ananke extract file.ts --verbose

# Try explicit language flag (coming soon)
# ananke extract file --language typescript

# Check if file contains actual code patterns
# Empty files or comments-only files yield no constraints

API / Integration Issues

Problem: Claude API errors (ANTHROPIC_API_KEY invalid)

Solution:

# Verify key is set
echo $ANTHROPIC_API_KEY

# Re-export if needed
export ANTHROPIC_API_KEY='sk-ant-...'

# Test API access
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Problem: Rate limit errors from Claude API

Solution:

Ananke caches extraction results automatically (30x faster on repeated runs)
Process files in smaller batches
Consider upgrading your Anthropic API tier

Example Build Issues

Problem: Examples fail to build with zig build run

Solution:

# Clean and rebuild from project root first
cd /path/to/ananke
zig build

# Then try example
cd examples/01-simple-extraction
zig build run

# If still fails, check example-specific build.zig
cat build.zig  # Look for hard-coded paths

Problem: Example shows hard-coded paths like /opt/homebrew/...

Solution: This is being fixed. For now, edit the example's build.zig:

// Remove hard-coded paths:
// exe.addSystemIncludePath(.{ .cwd_relative = "/opt/homebrew/..." });

// Replace with:
exe.linkSystemLibrary("tree-sitter");

Performance Tips

Slow Extraction

Problem: Constraint extraction takes >5 seconds per file

Possible causes:

First run (no cache) - expected
Very large files (>100KB) - consider splitting
Network issues with Claude API - check connectivity

Solutions:

# Use cache (automatic on repeated runs)
# First run: ~10ms, cached: ~0.3ms (30x faster)

# Disable Claude for faster syntactic-only extraction
unset ANTHROPIC_API_KEY
ananke extract file.ts  # Pure AST extraction, no API calls

# Process in parallel
find src -name "*.ts" | xargs -P 4 -I {} ananke extract {}

High Memory Usage

Problem: Process uses >500MB RAM

Solutions:

Process files one at a time instead of batch
Clear cache periodically (automatic, but can be manual)
Use smaller constraint sets

Getting More Help

If you're still stuck:

Check examples: examples/ directory has working code for common patterns
Read docs:
- LIBRARY_INTEGRATION.md - Library usage
- ARCHITECTURE.md - System design
- USER_GUIDE.md - Comprehensive guide
Search issues: GitHub Issues
Ask community: GitHub Discussions
Report bugs: Include:
- Zig version (zig version)
- OS and version
- Full error message
- Minimal reproduction steps

Resources

Main README: README.md
User Guide: docs/USER_GUIDE.md
Architecture: docs/ARCHITECTURE.md
Examples: examples/README.md
GitHub: https://github.com/ananke-ai/ananke

Get Help

GitHub Issues: Report bugs or ask questions
GitHub Discussions: Community support
Documentation: Check /docs directory

Ready to build with confidence? Start with Example 01 and work your way up!

cd examples/01-simple-extraction
zig build run

Happy constraining!

FilesExpand file tree

QUICKSTART.md

Latest commit

History

QUICKSTART.md

File metadata and controls

Ananke Quickstart Guide

What You'll Learn

Before You Start

What is Ananke?

How It Works

What You Need

Step 1: Build Ananke (3 minutes)

Step 2: Extract Your First Constraints (2 minutes)

Run the Example

What Did You Just Do?

Try It on Your Own Code

Step 3: Add Semantic Analysis with Claude (3 minutes, optional)

Set Up Claude (if you have an API key)

What's the Difference?

Step 4: See the Full Picture (5 minutes)

Understanding the Layers

What's Next?

For Learning

For Building

For Production

Common Questions

Q: Do I need Claude API for basic use?

Q: Can I generate code yet?

Q: How fast is constraint extraction?

Q: What languages are supported?

Q: How accurate is constraint extraction?

Q: What about false positives?

Troubleshooting

Build Fails

Examples Don't Run

Claude API Issues

"Zig not found"

Key Takeaways

The Full Pipeline (Now Available)

Troubleshooting

Common Issues

Build Errors

Memory Errors

Runtime Errors

API / Integration Issues

Example Build Issues

Performance Tips

Slow Extraction

High Memory Usage

Getting More Help

Resources

Get Help