# Option A — Ollama (local, no API key, recommended)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1

# Option B — OpenAI
pip install openai --break-system-packages

# Option C — Anthropic Claude
pip install anthropic --break-system-packages

from ros2_lingua_core import CapabilityRegistry

registry = CapabilityRegistry()

# Registration
registry.register(navigate)       # raises if already registered
registry.update(navigate)         # register or overwrite
registry.unregister("navigate_to_location")

# Querying
registry.get("navigate_to_location")
registry.get_all()
registry.get_by_tag("locomotion")
registry.get_by_tags(["locomotion", "manipulation"], match="any")
registry.get_by_tags(["manipulation", "social"], match="all")
registry.get_all_tags()           # sorted unique tag list
registry.get_untagged()           # caps with no tags

# State management
registry.set_state("robot_is_balanced")
registry.clear_state("robot_is_balanced")
registry.get_state()              # current Set[str]
registry.is_satisfied(["robot_is_balanced"])

from ros2_lingua_core import GroundingEngine, OllamaBackend

engine = GroundingEngine(
    registry=registry,
    backend=OllamaBackend(model="llama3.1"),
    auto_chain=True,   # insert prerequisites automatically
    max_retries=3,      # retry on timeout/rate limit
    retry_delay=1.0,    # initial wait in seconds
    retry_backoff=2.0,  # multiply wait on each retry
)

# Ground an instruction
plan = engine.ground("go to the table and pick up the bottle")

# Ground with tag filter — only consider locomotion caps
plan = engine.ground("move to position A", tag_filter=["locomotion"])

# Check the result
if plan.feasible:
    for step in plan.steps:
        print(step.capability_name, step.parameters)
else:
    print("Not feasible:", plan.reason)

# Given:
# stabilize_robot  → produces: [robot_is_balanced]
# navigate         → requires: [robot_is_balanced]  produces: [robot_at_location]
# pick_up_object   → requires: [robot_at_location, arm_is_free]

# Current state: {arm_is_free}  ← robot_is_balanced NOT yet true

chain = registry.resolve_chain(
    "pick_up_object",
    current_state={"arm_is_free"}
)

# Result: [stabilize_robot, navigate, pick_up_object]
# stabilize was auto-inserted because navigate needed robot_is_balanced

from ros2_lingua_core import OllamaBackend, OpenAIBackend, AnthropicBackend, RetryConfig

# Ollama — local, no API key
backend = OllamaBackend(model="llama3.1")

# OpenAI
backend = OpenAIBackend(api_key="sk-...", model="gpt-4o")

# Anthropic
backend = AnthropicBackend(api_key="sk-ant-...", model="claude-sonnet-4-20250514")

# Custom retry config
retry = RetryConfig(max_retries=5, base_delay_sec=2.0, backoff_factor=2.0)
backend = OllamaBackend(model="llama3.1", retry=retry)

# Custom backend — implement one method
class MyBackend:
    def complete(self, messages: list[dict]) -> str:
        return my_llm_call(messages)  # return response string

from ros2_lingua_core import (
    LinguaError,            # catch all ros2_lingua errors
    LLMBackendError,        # any LLM connectivity problem
    LLMTimeoutError,        # LLM took too long
    LLMRateLimitError,      # API rate limit hit
    LLMModelNotFoundError,  # model doesn't exist
    HallucinationError,     # LLM referenced unknown capability
    UnsatisfiablePreconditionError,
    StepTimeoutError,
    StepFailedError,
)

try:
    plan = engine.ground("pick up the bottle")
except LLMModelNotFoundError as e:
    print(f"Model not found: {e}. Try: ollama pull llama3.1")
except LLMBackendError as e:
    print(f"LLM connectivity issue: {e}")