instill¶
Full name: tenets.cli.commands.instill
Instill command - Smart injection of guiding principles into context.
This command provides comprehensive control over tenet injection including: - Multiple injection frequency modes (always, periodic, adaptive, manual) - Session-aware injection tracking - Complexity analysis for smart injection - History and statistics viewing - Export capabilities for analysis
Classes¶
Functions¶
Python
instill(session: Optional[str] = typer.Option(None, '--session', '-s', help='Target session for instillation'), force: bool = typer.Option(False, '--force', '-f', help='Force injection regardless of frequency settings'), frequency: Optional[str] = typer.Option(None, '--frequency', help='Override injection frequency (always/periodic/adaptive/manual)'), interval: Optional[int] = typer.Option(None, '--interval', help='Override injection interval for periodic mode'), dry_run: bool = typer.Option(False, '--dry-run', help='Show what would be instilled without applying'), analyze: bool = typer.Option(False, '--analyze', help='Analyze injection patterns and effectiveness'), stats: bool = typer.Option(False, '--stats', help='Show injection statistics'), list_pending: bool = typer.Option(False, '--list-pending', help='List pending tenets and exit'), list_history: bool = typer.Option(False, '--list-history', help='Show injection history for session'), list_sessions: bool = typer.Option(False, '--list-sessions', help='List all tracked sessions'), add_file: Optional[list[str]] = typer.Option(None, '--add-file', '-F', help='Pin a file for future distill operations (can be passed multiple times)'), add_folder: Optional[list[str]] = typer.Option(None, '--add-folder', '-D', help='Pin all files in a folder (respects .gitignore)'), remove_file: Optional[list[str]] = typer.Option(None, '--remove-file', help='Unpin a file from the session'), list_pinned: bool = typer.Option(False, '--list-pinned', help='List pinned files for the session and exit'), reset_session: bool = typer.Option(False, '--reset-session', help='Reset injection history for the session'), clear_all_sessions: bool = typer.Option(False, '--clear-all-sessions', help='Clear all session histories (requires confirmation)'), export_history: Optional[Path] = typer.Option(None, '--export-history', help='Export injection history to file (JSON or CSV)'), export_format: str = typer.Option('json', '--export-format', help='Format for export (json/csv)'), set_frequency: Optional[str] = typer.Option(None, '--set-frequency', help='Set default injection frequency and save to config'), set_interval: Optional[int] = typer.Option(None, '--set-interval', help='Set default injection interval and save to config'), show_config: bool = typer.Option(False, '--show-config', help='Show current injection configuration'), ctx: Context = typer.Context)
Smart injection of guiding principles (tenets) into your context.
This command manages the injection of tenets with intelligent frequency control, session tracking, and complexity-aware adaptation. Tenets are strategically placed to maintain consistent coding principles across AI interactions.
INJECTION MODES
always - Inject into every distilled context periodic - Inject every Nth distillation adaptive - Smart injection based on complexity manual - Only inject when forced
Text Only
# Standard injection (uses configured frequency)
tenets instill
# Force injection regardless of frequency
tenets instill --force
# Session-specific injection
tenets instill --session oauth-work
# Set injection to every 5th distill
tenets instill --set-frequency periodic --set-interval 5
# View injection statistics
tenets instill --stats --session oauth-work
# Analyze effectiveness
tenets instill --analyze
# Pin files for guaranteed inclusion
tenets instill --add-file src/core.py --session main
# Export history for analysis
tenets instill --export-history analysis.json
# Reset session tracking
tenets instill --reset-session --session oauth-work
Source code in tenets/cli/commands/instill.py
Python
def instill(
# Session management
session: Optional[str] = typer.Option(
None, "--session", "-s", help="Target session for instillation"
),
# Injection control
force: bool = typer.Option(
False, "--force", "-f", help="Force injection regardless of frequency settings"
),
frequency: Optional[str] = typer.Option(
None, "--frequency", help="Override injection frequency (always/periodic/adaptive/manual)"
),
interval: Optional[int] = typer.Option(
None, "--interval", help="Override injection interval for periodic mode"
),
# Analysis and preview
dry_run: bool = typer.Option(
False, "--dry-run", help="Show what would be instilled without applying"
),
analyze: bool = typer.Option(
False, "--analyze", help="Analyze injection patterns and effectiveness"
),
stats: bool = typer.Option(False, "--stats", help="Show injection statistics"),
# Listing options
list_pending: bool = typer.Option(False, "--list-pending", help="List pending tenets and exit"),
list_history: bool = typer.Option(
False, "--list-history", help="Show injection history for session"
),
list_sessions: bool = typer.Option(False, "--list-sessions", help="List all tracked sessions"),
# File pinning
add_file: Optional[list[str]] = typer.Option(
None,
"--add-file",
"-F",
help="Pin a file for future distill operations (can be passed multiple times)",
),
add_folder: Optional[list[str]] = typer.Option(
None,
"--add-folder",
"-D",
help="Pin all files in a folder (respects .gitignore)",
),
remove_file: Optional[list[str]] = typer.Option(
None,
"--remove-file",
help="Unpin a file from the session",
),
list_pinned: bool = typer.Option(
False, "--list-pinned", help="List pinned files for the session and exit"
),
# Session management
reset_session: bool = typer.Option(
False, "--reset-session", help="Reset injection history for the session"
),
clear_all_sessions: bool = typer.Option(
False, "--clear-all-sessions", help="Clear all session histories (requires confirmation)"
),
# Export options
export_history: Optional[Path] = typer.Option(
None, "--export-history", help="Export injection history to file (JSON or CSV)"
),
export_format: str = typer.Option(
"json", "--export-format", help="Format for export (json/csv)"
),
# Configuration
set_frequency: Optional[str] = typer.Option(
None, "--set-frequency", help="Set default injection frequency and save to config"
),
set_interval: Optional[int] = typer.Option(
None, "--set-interval", help="Set default injection interval and save to config"
),
show_config: bool = typer.Option(
False, "--show-config", help="Show current injection configuration"
),
# Context
ctx: typer.Context = typer.Context,
):
"""
Smart injection of guiding principles (tenets) into your context.
This command manages the injection of tenets with intelligent frequency control,
session tracking, and complexity-aware adaptation. Tenets are strategically
placed to maintain consistent coding principles across AI interactions.
INJECTION MODES:
always - Inject into every distilled context
periodic - Inject every Nth distillation
adaptive - Smart injection based on complexity
manual - Only inject when forced
Examples:
# Standard injection (uses configured frequency)
tenets instill
# Force injection regardless of frequency
tenets instill --force
# Session-specific injection
tenets instill --session oauth-work
# Set injection to every 5th distill
tenets instill --set-frequency periodic --set-interval 5
# View injection statistics
tenets instill --stats --session oauth-work
# Analyze effectiveness
tenets instill --analyze
# Pin files for guaranteed inclusion
tenets instill --add-file src/core.py --session main
# Export history for analysis
tenets instill --export-history analysis.json
# Reset session tracking
tenets instill --reset-session --session oauth-work
"""
state = {}
try:
_ctx = click.get_current_context(silent=True)
if _ctx and _ctx.obj:
state = _ctx.obj
except Exception:
state = {}
verbose = state.get("verbose", False)
quiet = state.get("quiet", False)
try:
# Load configuration
config = TenetsConfig()
tenets_instance = Tenets(config)
# Check if tenet system is available
if not hasattr(tenets_instance, "instiller") or not tenets_instance.instiller:
console.print("[red]Error:[/red] Tenet system is not available.")
console.print("This may be due to missing dependencies or configuration issues.")
raise typer.Exit(1)
instiller = tenets_instance.instiller
# ============= Configuration Commands =============
if show_config:
_show_injection_config(config)
return
if set_frequency:
_set_injection_frequency(config, set_frequency, set_interval)
return
# ============= Session Management =============
if list_sessions:
_list_sessions(instiller)
return
if clear_all_sessions:
if typer.confirm("Clear all session histories? This cannot be undone."):
_clear_all_sessions(instiller)
return
if reset_session:
if not session:
console.print("[red]Error:[/red] --reset-session requires --session")
raise typer.Exit(1)
_reset_session(instiller, session)
return
# ============= Listing Commands =============
if list_history:
_show_injection_history(instiller, session)
return
if stats:
_show_statistics(instiller, session)
return
if analyze:
_analyze_effectiveness(instiller, session)
return
if list_pending:
_list_pending_tenets(tenets_instance, session)
return
# ============= File Pinning =============
if list_pinned:
_list_pinned_files(tenets_instance, session)
return
if add_file or add_folder or remove_file:
_manage_pinned_files(tenets_instance, session, add_file, add_folder, remove_file, quiet)
if not (force or dry_run): # Only manage files, don't instill
return
# ============= Export =============
if export_history:
_export_history(instiller, export_history, export_format, session)
return
# ============= Main Instillation Logic =============
# Get injection frequency configuration
if frequency:
injection_frequency = frequency
else:
injection_frequency = config.tenet.injection_frequency
if interval:
injection_interval = interval
else:
injection_interval = config.tenet.injection_interval
# Get or create session
session_name = session or "default"
# Get session history if exists
if session_name in instiller.session_histories:
history = instiller.session_histories[session_name]
session_info = history.get_stats()
else:
session_info = None
# Show session status
if not quiet and session_info:
console.print(
Panel(
f"Session: [cyan]{session_name}[/cyan]\n"
f"Distills: {session_info['total_distills']}\n"
f"Injections: {session_info['total_injections']}\n"
f"Rate: {session_info['injection_rate']:.1%}\n"
f"Avg Complexity: {session_info['average_complexity']:.2f}",
title="Session Status",
border_style="blue",
)
)
# Check if injection should occur
if not force and injection_frequency != "manual":
# Simulate a distill to check frequency
test_context = "# Test Context\n\nChecking injection frequency..."
# This won't actually inject, just checks frequency
result = instiller.instill(
test_context,
session=session_name,
force=False,
check_frequency=True,
)
# Check if injection was skipped
last_record = (
instiller.metrics_tracker.instillations[-1]
if instiller.metrics_tracker.instillations
else None
)
if last_record and last_record.get("skip_reason"):
skip_reason = last_record["skip_reason"]
if not quiet:
console.print(
f"[yellow]Injection skipped:[/yellow] {skip_reason}\n"
f"Use --force to override or wait for next trigger."
)
# Show when next injection will occur
if "periodic" in injection_frequency:
next_at = (
(session_info["total_distills"] // injection_interval) + 1
) * injection_interval
console.print(f"Next injection at distill #{next_at}")
return
# Dry run mode
if dry_run:
_dry_run_instillation(tenets_instance, session_name, injection_frequency)
return
# Perform instillation
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
console=console,
transient=True,
) as progress:
progress.add_task("Instilling tenets...", total=None)
# Create sample context for demonstration
sample_context = (
"# Sample Context\n\n"
"This is a demonstration of tenet injection.\n"
"The instiller will analyze this context and inject "
"appropriate tenets based on the configured strategy."
)
result = instiller.instill(
sample_context,
session=session_name,
force=force,
strategy=None, # Use configured strategy
check_frequency=not force,
)
# Get the last instillation result
if instiller._cache:
last_key = list(instiller._cache.keys())[-1]
last_result = instiller._cache[last_key]
if not quiet:
_show_instillation_result(last_result, verbose)
except Exception as e:
console.print(f"[red]Error:[/red] {e!s}")
if verbose:
console.print_exception()
raise typer.Exit(1)