CLI

# Run an agent with input
orbiter run "What is Python?"

# Run with explicit config
orbiter run --config agents.yaml "Explain decorators"

# Run with model override
orbiter run -m openai:gpt-4o "Hello"

# Enable streaming
orbiter run --stream "Tell me a story"

# Verbose output
orbiter --verbose run "Debug this code"

from orbiter_cli import find_config, load_config, resolve_config

# Auto-discover config
path = find_config()  # searches cwd for .orbiter.yaml or orbiter.config.yaml

# Load explicit config
config = load_config("agents.yaml")

# Resolve (explicit or auto-discovered)
config = resolve_config(config_path=None)  # auto-discovers
config = resolve_config(config_path="my-config.yaml")  # explicit

# agents/research.py
from orbiter.agent import Agent

def create_agent():
    return Agent(
        name="researcher",
        model="openai:gpt-4o",
        instructions="You are a research assistant.",
    )

def create_agent():
    return {
        "researcher": Agent(name="researcher", ...),
        "writer": Agent(name="writer", ...),
    }

# agents/team.yaml
agents:
  assistant:
    model: openai:gpt-4o
    instructions: You are a helpful assistant.
  coder:
    model: openai:gpt-4o
    instructions: You write Python code.

---
name: writer
model: openai:gpt-4o
temperature: 0.7
max_tokens: 2000
---

You are a creative writer. You write engaging stories,
articles, and blog posts. Use vivid language and
compelling narratives.

from orbiter_cli import discover_agent_files, scan_directory, validate_agent

# Find agent files in a directory
files = discover_agent_files("/path/to/agents")
# Returns .py, .yaml, .md files sorted by name

# Scan and load all agents
agents = scan_directory("/path/to/agents", validate=True)
# Returns dict: name -> agent instance

# Validate an agent instance
validate_agent("my_agent", agent)  # checks for 'name' and 'run' attributes

from orbiter_cli import InteractiveConsole

console = InteractiveConsole(
    agents={"assistant": my_agent, "coder": coding_agent},
    run_fn=my_run_function,
    stream_fn=my_stream_function,  # optional
    streaming=True,
)

await console.start()

from orbiter_cli import parse_command

cmd, arg = parse_command("/switch researcher")
# cmd = "switch", arg = "researcher"

cmd, arg = parse_command("Hello, how are you?")
# cmd = "", arg = "Hello, how are you?"

from orbiter_cli import format_agents_table

table = format_agents_table(agents)
# Rich Table with Name, Model, Description columns

from orbiter_cli import LocalExecutor

executor = LocalExecutor(
    agent=my_agent,
    provider=None,       # auto-resolved
    timeout=60.0,        # seconds (0 = no timeout)
    max_retries=3,
    verbose=True,
)

# Non-streaming execution
result = await executor.execute("What is Python?")
print(result.output)     # agent output text
print(result.steps)      # number of LLM steps
print(result.elapsed)    # wall-clock seconds
print(result.usage)      # {"prompt_tokens": ..., "output_tokens": ..., "total_tokens": ...}
print(result.summary())  # "3 step(s), 2.1s, 1500 tokens"

# Streaming execution
async for chunk in executor.stream("Tell me a story"):
    print(chunk, end="")

# Display helpers
executor.print_result(result)  # Rich panel with output
executor.print_error(error)    # Red error message

from orbiter_cli import load_batch_items, BatchItem, InputFormat
from orbiter_cli.batch import batch_execute, results_to_jsonl, results_to_csv

# Load inputs from file
items = load_batch_items(
    "inputs.jsonl",
    input_key="input",    # column/field with agent input
    id_key="id",          # column/field with item ID
)

# Execute batch with concurrency control
result = await batch_execute(
    agent=my_agent,
    items=items,
    concurrency=4,     # max parallel executions
    timeout=30.0,      # per-item timeout
)

print(result.summary())  # "100 items: 95 succeeded, 5 failed"

# Export results
jsonl = results_to_jsonl(result)
csv = results_to_csv(result)

from orbiter_cli import BatchItem

item = BatchItem(
    id="item-1",
    input="What is Python?",
    metadata={"category": "programming"},
)

from orbiter_cli import PluginSpec, PluginHook

async def on_startup(**kwargs):
    print("CLI starting up!")

async def on_pre_run(**kwargs):
    print("About to run agent...")

async def on_post_run(**kwargs):
    print("Agent finished!")

async def on_shutdown(**kwargs):
    print("CLI shutting down!")

plugin = PluginSpec(
    name="my-plugin",
    version="1.0.0",
    description="Example CLI plugin",
    hooks={
        PluginHook.STARTUP: on_startup,
        PluginHook.PRE_RUN: on_pre_run,
        PluginHook.POST_RUN: on_post_run,
        PluginHook.SHUTDOWN: on_shutdown,
    },
)

from orbiter_cli import PluginManager

manager = PluginManager()

# Load from Python entry points
loaded = manager.load_entrypoints()
print(f"Loaded {loaded} plugins from entry points")

# Load from a directory
loaded = manager.load_directory("/path/to/plugins")

# Register manually
manager.register(my_plugin_spec)

# Run lifecycle hooks
await manager.startup()
await manager.run_hook(PluginHook.PRE_RUN, agent=agent, input=text)
await manager.shutdown()

# pyproject.toml
[project.entry-points."orbiter.plugins"]
my_plugin = "my_package:plugin"

# plugins/my_plugin.py
from orbiter_cli import PluginSpec, PluginHook

plugin = PluginSpec(
    name="my-plugin",
    hooks={PluginHook.STARTUP: on_startup},
)

from orbiter_cli import find_config, load_config

config = load_config("custom-agents.yaml")
agents = config.get("agents", {})

from orbiter_cli import load_batch_items, InputFormat

# Force a specific format
items = load_batch_items("data.txt", fmt=InputFormat.JSONL)

# Custom input/id keys
items = load_batch_items("data.csv", input_key="prompt", id_key="case_id")

manager = PluginManager()
manager.load_entrypoints()
manager.load_directory("./plugins")

await manager.startup()

try:
    await manager.run_hook(PluginHook.PRE_RUN, agent=agent, input=text)
    result = await executor.execute(text)
    await manager.run_hook(PluginHook.POST_RUN, result=result)
finally:
    await manager.shutdown()