QUICKSTART.md

Warbler CDA - Quick Start Guide

🚀 Quick Start (3 options)

📝 Home may not be available on path immediately

# set home path for environment
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# start the terminal
source ~/.bashrc

Option 1: Local Python (Recommended for Development)

cd warbler-cda-package
./setup.sh
python app.py

Open http://localhost:7860

Option 2: Docker

cd warbler-cda-package
docker-compose up warbler-cda-demo

Open http://localhost:7860

Option 3: HuggingFace Space (Recommended for Sharing)

1. Create a HuggingFace Space at https://huggingface.co/new-space
2. Choose "Gradio" as SDK
3. Upload the warbler-cda-package/ contents
4. Your Space will be live at https://huggingface.co/spaces/YOUR_USERNAME/warbler-cda

📚 Usage Examples

Example 1: Basic Query

from warbler_cda import RetrievalAPI, EmbeddingProviderFactory

# Initialize
embedding_provider = EmbeddingProviderFactory.get_default_provider()
api = RetrievalAPI(embedding_provider=embedding_provider)

# Add document
api.add_document(
    doc_id="wisdom_1",
    content="Courage is not the absence of fear, but acting despite it.",
    metadata={"realm_type": "wisdom", "realm_label": "virtue"}
)

# Query
results = api.query_semantic_anchors("What is courage?", max_results=5)
for result in results:
    print(f"{result.relevance_score:.3f} - {result.content}")

Example 2: FractalStat Hybrid Scoring

from warbler_cda import FractalStatRAGBridge, RetrievalQuery, RetrievalMode

# Enable FractalStat
fractalstat_bridge = FractalStatRAGBridge()
api = RetrievalAPI(
    embedding_provider=embedding_provider,
    fractalstat_bridge=fractalstat_bridge,
    config={"enable_fractalstat_hybrid": True}
)

# Query with hybrid scoring
query = RetrievalQuery(
    query_id="hybrid_1",
    mode=RetrievalMode.SEMANTIC_SIMILARITY,
    semantic_query="wisdom about resilience",
    fractalstat_hybrid=True,
    weight_semantic=0.6,
    weight_fractalstat=0.4
)

assembly = api.retrieve_context(query)
print(f"Quality: {assembly.assembly_quality:.3f}")
print(f"Results: {len(assembly.results)}")

Example 3: API Service

# Start the API
uvicorn warbler_cda.api.service:app --host 0.0.0.0 --port 8000

# In another terminal, use the CLI
warbler-cli query --query-id q1 --semantic "wisdom about courage" --hybrid

# Or use curl
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query_id": "test1",
    "semantic_query": "wisdom about courage",
    "fractalstat_hybrid": true
  }'

🔧 Configuration

Embedding Providers

# Local TF-IDF (default, no API key needed)
from warbler_cda import EmbeddingProviderFactory
provider = EmbeddingProviderFactory.create_provider("local")

# OpenAI (requires API key)
provider = EmbeddingProviderFactory.create_provider(
    "openai",
    config={"api_key": "your-api-key", "model": "text-embedding-ada-002"}
)

FractalStat Configuration

# Custom FractalStat weights
api = RetrievalAPI(
    fractalstat_bridge=fractalstat_bridge,
    config={
        "enable_fractalstat_hybrid": True,
        "default_weight_semantic": 0.7,  # 70% semantic
        "default_weight_fractalstat": 0.3       # 30% FractalStat
    }
)

📊 Running Experiments

from warbler_cda import run_all_experiments

# Run FractalStat validation experiments
results = run_all_experiments(
    exp01_samples=1000,
    exp01_iterations=10,
    exp02_queries=1000,
    exp03_samples=1000
)

print(f"EXP-01 (Uniqueness): {results['EXP-01']['success']}")
print(f"EXP-02 (Efficiency): {results['EXP-02']['success']}")
print(f"EXP-03 (Necessity): {results['EXP-03']['success']}")

🐛 Troubleshooting

Import Errors

If you see import errors, make sure the package is installed:

pip install -e .

Missing Dependencies

Install all dependencies:

pip install -r requirements.txt

Gradio Not Starting

Check if port 7860 is available:

lsof -i :7860  # Linux/Mac
netstat -ano | findstr :7860  # Windows

📖 More Information

• Full documentation: README.md
• Deployment guide: DEPLOYMENT.md
• Contributing: CONTRIBUTING.md
• Package manifest: PACKAGE_MANIFEST.md