Smarter Documentation

Teaching and Training

  • Smarter Instructor Guide
    • Open Source, Free, and Community Supported
    • From Educational Sandbox to Live Production
    • Free Course Designs
    • Getting Smarter Running
      • Quick Start
      • From Source
      • The Command-Line Interface
      • A First Look Around
    • Setting Up a Class
      • Choosing a Deployment Model
      • Accounts and Users
      • Managing Cost
      • Privacy and Academic Integrity
    • Planning a Course
      • Sample Formats
      • Assignments and Grading
    • Instructor Checklist
    • Getting Help and Giving Back
  • Free Course Designs
    • Micro Courses
      • Course Formats and Grading
        • The Three Formats
        • Grading
        • Course Policies
        • Before Teaching a Plan
      • Prompt Engineering
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Building AI Applications
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • AI Governance and Responsible AI
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • The Economics of AI
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Backend Development with Python, Django, Django REST Framework and Pydantic
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Front End Development with React, Vite.js and Bootstrap
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Full Stack Development with Django and React
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • API Design and Integration
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Extension Development
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • AI Features in Software
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Writing Secure Software for the Internet
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Docker for Software Development
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Kubernetes for Running Applications at Scale
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Cloud Infrastructure as Code
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Self-Hosting Open Models
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Software Quality and Quality Assurance
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Creating High Quality Documentation with Sphinx
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Software Architecture
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Agentic Software Development with Claude Code
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
      • Open Source Participation
        • Classroom bootcamp: 8 hours
        • Two-week online course: 6 hours
        • Four-week online course: 12 hours
    • Master Classes
      • Django Master Class
        • Three-day classroom course: 18 hours
        • Six-week online course: 18 hours
      • AI Application Development Master Class
        • Three-day classroom course: 18 hours
        • Six-week online course: 18 hours
      • Python Programming with Agentic AI Master Class
        • Three-day classroom course: 18 hours
        • Six-week online course: 18 hours
  • Case Studies
    • Shadow AI: Taking Control of the AI Projects Already Running
      • At a glance
      • Executive summary
      • Background
      • The challenge
        • What leaving it there costs
        • The requirements
      • Options considered
      • The solution
        • General Amnesty Granted
        • Phase 1: a Proxy for every project
        • One project, one key
        • Spending: attributed, and capped
        • The inventory
        • Phase 2: rebuild what sends too much
        • The two phases, side by side
      • Implementation
      • Results
      • Lessons for practitioners
      • Sources
    • Ask Stanley: Answers for Prospective Students, at Any Hour
      • At a glance
      • Executive summary
      • Background
        • The first chatbot
        • The people
      • The challenge
      • Options considered
      • The solution
        • How Stanley answers a question
        • The tool: one reviewed query
        • Accurate: the database, not the model
        • Need to know: only what the question needs
        • Timely: a chat window that never closes
        • Safe to expose: the catalogue, and nothing else
        • Bounded: a budget with a hard stop
        • How each role uses it
        • What Stanley doesn’t do yet
      • Implementation
      • Results
      • Lessons for practitioners
      • Sources
    • Organizing for AI: Everyone Can Ask the Data
      • At a glance
      • Executive summary
      • Who is Stackademy?
      • The organization and its people
      • What the platform has to do
      • How each role uses it
        • The Head of IT: Tomas Hartigan
        • Human Resources: Avery Ivanova and Quinn Sandoval
        • The CFO and Accounting: Odette Hartigan and Kofi Sandoval
        • Course Content: Odette Eriksen and Tomas Underhill
        • Admissions: Dmitri Dumont and Wren Dumont
        • The executives: Vera Jaramillo and Odette Hartigan
      • How it fits together
      • Results
      • Lessons for practitioners
      • Sources
    • Confidential by Construction: AI Assistants over One Company Database
      • At a glance
      • Executive summary
      • Background
      • The challenge
      • Options considered
      • The solution
      • Implementation
      • Results
      • Lessons for practitioners
      • Sources
    • The Board Pack: Orchestrating Assistants Across Organizational Boundaries
      • At a glance
      • Executive summary
      • Background
      • The challenge
      • Options considered
      • The solution
      • Implementation
      • Results
      • Lessons for practitioners
      • Sources
    • The Smarter Doodle: Celebrating Special Days, Without an Artist or an Arbiter
      • At a glance
      • Executive summary
      • Background
        • The roles
      • The challenge
      • Options considered
      • The solution
        • 1. The calendar: a catalog, and a planner
        • 2. The candidates: what the editor may choose from
        • 3. The editor: a Smarter LLMClient
        • 4. The checks: Python, whatever the prompt says
        • 5. The tone judge: a Guardrail, called by code
        • 6. The artist: a second LLMClient
        • 7. The sanitizer: Python, by allowlist
        • 8. The superuser: approval, not arbitration
        • Credit, and a record
      • Implementation
      • Results
      • Lessons for practitioners
      • Sources

Community

  • Smarter on Slack
    • What the Bot Is
    • Talking to the Bot
      • In a channel
      • In a direct message
      • Getting help
      • Waiting for the answer
    • Asking Good Questions
    • How Answers Look in Slack
    • Limits
    • Privacy
    • When to Ask a Person
    • Troubleshooting
    • Running Your Own

Smarter Docs

  • Platform Administration Guide
    • Installation
      • Quick Start Guide
        • 1. Install Docker Desktop.
        • 2. Clone the Repository.
        • 3. Prepare Your Environment File.
        • 4. Initialize the Application.
        • 5. Start the Application.
        • 6. Log In.
        • 7. Download the Smarter Command-Line Interface.
      • Production Deployment
        • I. Infrastructure
        • II. Smarter Platform Application
        • Trouble Shooting
      • Developer Setup Guide
        • Prerequisites
        • Launch the Smarter Platform
        • Work With Source Code
        • Good Coding Best Practices
        • Repository Setup
        • Docker Setup
        • Python Setup
        • Keen Bootstrap Theme Setup
        • AWS Cloud Infrastructure
    • Smarter Web Console
      • AI Resource Authors
        • Sign-in Page
        • Console Dashboard
        • User Menu
        • Languages
        • AI Resource Lists
        • LLM Prompt Workbench
        • Apply Manifest
        • LLM Provider API Passthrough Tool
        • Live Server Logs
        • Complete REST API Reference
      • Administrators
        • Django Admin Console
        • Terminal
    • Django Admin
    • Managing Extensions
      • The Extensions Page
      • Installing from the Registry
        • Trust Badges
      • Uploading an Extension
      • An Extension’s Page
        • Configuring an Extension
        • Availability
      • Enabling and Disabling
      • Updates
        • Rolling Back
      • Uninstalling an Extension
      • When Something Goes Wrong
      • Configuring the Registry
      • Management Commands
    • Prerequisites
    • Trouble Shooting & FAQ
    • Cloud Infrastructure
      • Usage
      • Resources Created
    • URL Patterns
      • Example URL Patterns
    • Account Management
      • Creating Accounts
    • User Management
    • Smarter CLI
    • API Keys
      • Creating API Keys
      • Managing API Keys
      • Configuration Options
      • Using API Keys
        • Smarter Chat React Component
        • Smarter Command-line Interface
    • How-To: Adding an LLM Provider to Smarter
      • Goal
      • Supported Providers
      • Prerequisites
      • Setup
        • Step 1: Get an API Key
        • Step 2: Add the Key to Smarter
      • Concept Overview
      • Step-by-Step: Create and Apply a Provider Manifest
        • Step 3: Generate a Starting Template
        • Step 4: Write the Provider Manifests
        • Step 5: Apply Both Manifests
        • Step 6: Confirm Both Providers are Active
      • Proof of Concept
      • Troubleshooting
    • Cost Accounting
      • Pricing
      • Budgets
        • Enforcement
        • Budget versus actual
    • Smarter Journal
      • Enabling the Smarter Journal
      • Django Log
      • Application Logs
    • MCPServer
      • Endpoints
      • Public Tools
        • The Index
        • GitHub Issues
        • Pull Requests
        • Daily Pod Log Review
      • Staff-Only Tools
        • Authentication
        • Smarter Sysadmin
        • Audit Trail
        • What a Reply May Say
      • The Built-in MCPClients
      • Technical Reference
        • Views
        • Authentication
        • MCP Protocol Base
        • Public Endpoint
        • Staff-Only Endpoint
        • Tool Sets
        • Rate Limit
        • Tool Result Cache
        • Public Tool Base Class
        • Staff-Only Tool Base Class
        • Search Tools
        • Reading Tools
        • Markdown Helpers
        • Manifest Tools
        • GitHub Tools
        • Status Tools
        • Log Tools
        • Help Desk Tools
        • Services
        • Repositories
        • Repository Indexer
        • Blog Indexer
        • Index Readiness
        • Search
        • Reading
        • Manifest Schemas
        • GitHub Client
        • GitHub Issues
        • GitHub Pull Requests
        • Acting User
        • Pod Logs
        • Status Report
        • Cluster Snapshot
        • Backing Services
        • Upstream Status Pages
        • User Support Snapshot
        • Reply Rules
        • URLs
        • Django ORM
        • Django Admin
        • Celery Tasks
        • Signals
        • Signal Receivers
        • Exceptions
        • Constants
        • Management Command
    • Configuration
      • 1. AWS Infrastructure Configuration
      • 2. Django Settings
      • 3. Asynchronous Task Queue Configuration
      • 4. Beat Scheduler Configuration
      • 5. Helm Chart Configuration
      • 6. Dockerfile Configuration
      • 7. GitHub Actions Secrets Configuration
      • 8. Secrets Management
      • 9. Logging Configuration
      • 10. Database Configuration
      • 11. Email/Notification Configuration
      • 1. Static & Media Files Configuration
      • 13. Smarter Settings Class Reference
    • Security
      • Firewall
      • Application Security
        • Proprietary Security Features
        • Django Security Features
      • Secure Remote Access
        • Smarter Authentication
      • Audit Logging
      • Malware Protection
      • User management
      • Data Encryption
      • Security Updates
    • Backup and Restore
    • Updates
    • Trouble Shooting
      • Where to go for Help
    • Security FAQ
  • Smarter AI Resource Reference
    • Smarter Account
      • Overview
      • Usage
      • Technical Reference
        • API Reference
        • manage.py Commands
        • Const
        • Hierarchy
        • Account Django ORM
        • Receivers
        • Repository Owners
        • Repository Scripts
        • Smarter Resources - Account
        • Smarter API Manifests (SAM)
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • User Merge
        • Utils
    • Smarter Authtoken
      • Overview
      • Overview
      • Technical Reference
    • Smarter Budget
      • Overview
      • Technical Reference
        • Budget Model
        • Budget
        • Budget
    • Smarter Connection
      • Overview
      • Example Manifest
      • Technical Reference
        • API Reference
        • Const
        • Manifest
        • Django ORM
        • Receivers
        • SAM Resources
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • URLs
        • Views
    • Smarter Custom Domain
      • Overview
      • How It Works
      • The Manifest
      • Verification
    • Smarter Guardrail
      • Overview
      • How It Works
      • The Manifest
        • Strategies
        • Actions
        • Modes and Failure
      • Built-in Guardrails
      • Security Notes
      • Technical Reference
        • Django Admin
        • API Reference
        • Caching
        • Const
        • Exceptions
        • Smarter API Manifests (SAM)
        • Django ORM
        • Signal Receivers
        • DRF Serializers
        • Services
        • Signals
        • Asynchronous Tasks
        • Views
    • Smarter LLM Client
      • Overview
      • Usage
      • Web Pages That Embed It
      • Staff-Only LLMClients
      • Model Settings
      • Styling the Chat
        • Styling Your LLMClient’s Chat
      • Example Manifest
      • Technical Reference
        • API Reference
        • Models
        • Smarter API Manifests (SAM)
        • DRF Serializers
        • React UI
        • LLMClientHelper Class
        • Kubernetes Ingress
        • Management Commands
        • Middleware
        • Tasks
        • Signals
        • URLs
        • Utils
        • Views
      • Sandbox Mode
      • Deploying
      • Updating
      • Deleting
      • Testing
      • Monitoring
      • Scaling
      • Trouble Shooting
    • Smarter LLM Host
      • Overview
      • Example: Self-Hosting a Hugging Face Model
      • Technical Reference
        • API Reference
        • Const
        • Management Commands
        • Smarter API Manifests (SAM)
        • Django ORM
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • Views
    • Smarter MCP Client
      • Overview
      • How It Works
      • The Manifest
        • Authentication
        • Security
      • Example Manifests
      • Technical Reference
        • API Reference
        • Caching
        • MCP Server Connections
        • Const
        • Exceptions
        • Smarter API Manifests (SAM)
        • Django ORM
        • Signal Receivers
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • Prompt Toolkit
        • Views
    • Smarter Orchestrator
      • Overview
      • Harnesses in other accounts
      • Running an Orchestrator
      • Technical Reference
        • API Reference
        • Const
        • Management Commands
        • Smarter API Manifests (SAM)
        • Django ORM
        • Runtime
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • Views
    • Smarter LLMTool Plugin
      • Overview
      • Usage
      • Example Manifest
      • Technical Reference
        • API Reference
        • Caching
        • Const
        • How it Works
        • How LLM Tool Calling Works
        • LLMTool Plugin Reference
        • Django Management Commands
        • Django ORM
        • Smarter API Manifests (SAM)
        • DRF Serializers
        • Natural Language Processing (NLP)
        • Signals
        • Receivers
        • Asynchronous Tasks
        • Views
    • Smarter Prompt
      • Overview
      • Usage
      • Technical Reference
        • Example Prompt Configuration
        • Example Prompt Request
        • Example Prompt Response
        • API Reference
        • Const
        • Manifests (SAM)
        • Django ORM
        • Django Management Commands
        • Signals
        • Asynchronous Tasks
        • Urls
        • Prompt Views
    • Smarter Provider
      • Overview
      • Technical Reference
        • API Reference
        • Const
        • Management Commands
        • Smarter API Manifests (SAM)
        • Django ORM
        • DRF Serializers
        • Services
        • Signals
        • Asynchronous Tasks
        • Utils
        • Verification
        • Views
    • Smarter Proxy
      • Overview
      • How It Works
      • Quick Start
      • Creating a Proxy
      • Manifest Reference
      • Authentication
      • Errors
      • Security
      • Usage and Budgets
      • Built-in Proxies
      • Technical Reference
        • API Reference
        • Authentication
        • Caching
        • Const
        • Exceptions
        • Smarter API Manifests (SAM)
        • Django ORM
        • Serializers
        • Passthrough Service
        • Signals
        • Views
    • Smarter Secret
      • Overview
      • Technical Reference
        • API Reference
        • Django Admin
        • Caching
        • Const
        • Management Commands
        • Smarter API Manifests (SAM)
        • Django ORM
        • Receivers
        • Secret Resources
        • DRF Serializers
        • Signals
        • Asynchronous Tasks
        • Urls
        • Views
    • Smarter Vectorsearch
      • API Reference
        • DefaultVectorsearchApiView
      • Const
      • Management Commands
      • Smarter API Manifests (SAM)
        • Enumerations Classes
        • Pydantic Models
      • Django ORM
        • Vectorsearch
        • VectorsearchSearchType
      • DRF Serializers
        • VectorsearchSerializer
      • Signals
        • vectorsearch_called
      • Asynchronous Tasks
      • Views
        • API View
        • ListView
        • Detail View
    • Smarter Vectorstore
      • Overview
      • Example Manifests
      • Lifecycle
        • Self-Hosted Qdrant
        • Managed Services
      • Documents
      • Search
      • Maintenance and Snapshots
      • Technical Reference
        • REST API
        • Vectorstore Backends
        • Caching
        • Management Commands
        • Documents: Text Extraction and Embeddings
        • Self-Hosted Qdrant on Kubernetes
        • Vectorstore Manifest
        • Vectorstore ORM Models
        • Vectorstore Receivers
        • Vectorstore Serializers
        • Vectorstore Services
        • Vectorstore Signals
        • Vectorstore Asynchronous Tasks
        • Web Console Views
  • Smarter Development Framework
    • The Smarter Ecosystem
      • Command Line and Editor
      • SDKs
      • Shared Python Libraries
      • Chat and Web Components
      • Running the Platform
      • Extending Smarter
    • How the Framework Fits Together
      • Getting Started
      • Smarter Architecture
        • Linux
        • Third-Party Django Apps
        • Smarter Subsystems
        • Smarter Django Apps
      • Extensibility
        • Plugins, Extensions and MCP Servers Compared
        • Where to Go Next
      • Smarter LLM Tool Extensions
        • An Extension in Brief
      • Developer Guides
        • Contributing
        • New Feature Checklist
        • Documentation Style Guide & Technical Reference
        • 12-Factor App
        • Code of Conduct
        • Developer Guidelines
        • Semantic Versioning Guide
        • OpenAI
        • OpenAI JSON Examples
        • Claude Code
      • Smarter APIs, SDKs and Integrations
        • The APIs
        • SDKs and Developer Tools
        • Website Integrations
        • Design Goals
        • Writing an SDK for Another Language
      • Smarter Broker Model
        • AbstractBroker
        • BrokerNotImplemented
        • KNOWN_KINDS
        • MetaModelT
        • ModelT
        • OwnedModelT
        • RowT
        • SAMDependency
        • SAMDependencyReference
        • SAMDependents
        • dependents_exist()
        • first_arg_of_type()
        • memoized_dependencies()
        • rows_with_pk()
        • should_log()
      • Smarter Chat
        • Where to Start
        • See Also
      • Smarter on Kubernetes
        • LLMClient Deployment
        • Operating Smarter at Scale
        • The Slack Bot
        • The Services
        • Docker and Kubernetes Compared
        • How Smarter Talks to the Cluster
        • Cluster Prerequisites
      • Developer Technical Reference
        • Agentic Development
        • Django-React Integration
        • Web Console Api
        • Translations
        • Smarter Journal
        • Smarter Enumeration Classes
        • Smarter Types
        • Smarter Mixins
        • Smarter Settings
        • Smarter Utils
        • Smarter Devops Guide
        • Smarter Dashboard App
        • Smarter Framework Library
      • Technologies
        • Amazon Web Services (AWS)
        • Docker
        • Infrastructure Services
        • Kubernetes
        • OpenTelemetry Compatibility
        • Python
        • Pydantic
        • SMTP Email Support
        • Tavily Web Search
  • ADR
    • ADR Introduction
      • Guidelines for Writing ADRs
    • ADR-001: Django
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-002: Docker
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-003: Kubernetes
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-004: 12-Factor App
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-005: Manifests
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-006: Rest API
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-007: Settings
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-008: Function Calling
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-009: Async Tasks
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-010: Management Commands
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-011: Logging
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-012: Error Handling
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-013: Testing
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-014: CI/CD
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-015: Dependency Management
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-016: Security
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-017: Database
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-018: Caching
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-019: React
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-020: Semantic Versioning
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-021: Internationalization
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-022: Feature Flags
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-023: API Versioning
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-024: Broker Model
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-025: Django Templates
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-026: Keen Bootstrap
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-027: Python Annotations
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-028: Code Quality
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR 029: Docstring Style
      • Context
      • Alternatives Considered
      • Decision
      • Consequences
      • References
    • ADR-030: Operational and Infrastructure Task Queues
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-031: Pydantic Models Over Raw JSON
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-032: Url Names Derived From View Classes
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-033: Don’t Repeat Yourself
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-034: The Web Console Api
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-035: The Web Console as a Single-Page App
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-036: Account Hierarchy and Resource Sharing
      • Status
      • Context
      • Decision
        • Worked example: Stackademy
      • Alternatives Considered
      • Consequences
      • Related ADRs
    • ADR-037: Orchestration Runtime
      • Status
      • Context
      • Decision
      • Alternatives Considered
      • Consequences
      • Related ADRs
  • Contributors
    • GitHub Repositories
    • Core Contributors
      • Becoming a Core Contributor
    • Community Contributors

External Resources

  • Support Smarter!
  • Smarter OpenAPI Contract
  • Smarter Manifest Examples
  • Smarter Json Schemas
  • Smarter on YouTube
Smarter Documentation
  • Smarter Development Framework
  • Technologies
  • Tavily Web Search
  • View page source

Tavily Web Search

Tavily is a commercial web search API that is designed for LLMs and AI agents. Like a search engine, it takes a query and returns ranked web pages, but each result is returned as structured json (a title, a url, a snippet of the page’s content, and its publication date) rather than as a page of links for a person to read. This makes it a good fit for tool calling, where the LLM reads the results and cites them.

Smarter uses Tavily as one of the two web search APIs of the WebsearchPlugin. The other is the Brave Search API. Each WebsearchPlugin chooses its search API in its manifest.

Note

The WebsearchPlugin is experimental. See WebsearchPlugin.

How Smarter Uses Tavily

The WebsearchPlugin. A WebsearchPlugin gives an LLM one tool with two operations: search the web, and read a web page. Only search uses Tavily. When the LLM sets a query, the plugin sends it to the Tavily Search API, https://api.tavily.com/search, and returns the results to the LLM in the same form as Brave’s, so that the LLM sees the same fields whichever API is configured. Reading a web page, the fetch operation, is done by Smarter itself, not by Tavily.

The plugin’s manifest selects Tavily, and names the Smarter Secret that contains the Tavily API key:

spec:
  websearchData:
    search:
      provider: tavily
      apiKey: tavily_api_key    # the name of a Smarter Secret, never the key itself
      maxResults: 5
      safeSearch: moderate
    blockedDomains:
      - pinterest.com

Each search request:

  • uses Tavily’s basic search depth and general topic, and asks for no generated answer and no raw page content, only ranked results.

  • passes the plugin’s allowedDomains and blockedDomains to Tavily, as its include_domains and exclude_domains. Smarter also filters the results that Tavily returns by the same domain policy, so that the policy is enforced even if Tavily returns a result that it should not.

  • passes safeSearch as Tavily’s safe_search, which is either on or off: moderate and strict both turn it on.

  • passes freshness (day, week, month or year) and language. The plugin’s country is not passed, because Tavily localizes by country name rather than by country code.

Search results are cached, per plugin, for the manifest’s cacheTtl seconds, keyed on the query and its parameters. A repeated question does not call Tavily again until the cache expires.

The implementation is smarter.apps.llmtool.plugin.websearch_providers.TavilySearchProvider.

The sample WebsearchPlugin. smarter_project_websearch uses Tavily to find current information about The Smarter Project on the web, from reputable sources. It is an example to copy, and no example LLMClient uses it. Its manifest is plugins/websearch/websearch-smarter-project.yaml, in the example manifests repository.

manage.py initialize_platform and manage.py initialize_account apply the sample plugins, with manage.py load_from_github. Applying smarter_project_websearch fails if its Secret tavily_api_key does not exist. The other plugins are not affected: each manifest is applied in its own transaction, so a manifest that fails is rolled back entirely, and is reported, and the command goes on to the next one.

Setup

  1. Get an API key. Create an account at tavily.com, and copy an API key from its dashboard. Tavily keys begin with tvly-.

  2. Set the environment variable. Set TAVILY_API_KEY. As with every Smarter setting, the name may also be given the SMARTER_ prefix, SMARTER_TAVILY_API_KEY: the two are the same setting. For local development, add it to .env, which .env.example documents:

    SMARTER_TAVILY_API_KEY=tvly-...
    
  3. Create the Secret. manage.py initialize_providers, which manage.py initialize_platform runs, stores the key as the Smarter Secret tavily_api_key, owned by the smarter admin. It updates the Secret if it already exists, so running it again rotates the key.

    python manage.py initialize_providers
    

    If TAVILY_API_KEY is not set, or is still a placeholder, such as SET-ME-PLEASE or values.yaml’s SET-ME-IN-helm/charts/smarter/values.yaml, the command does not create the Secret, and lists the key in the [API KEYS NOT SET] console error that it logs at the end, with the other missing API keys. It never stores a placeholder as the key.

  4. Apply the sample plugins.

    python manage.py load_from_github --url https://github.com/smarter-sh/example-manifests --include_kind WebsearchPlugin
    

Other WebsearchPlugins can use the same Secret, by setting apiKey: tavily_api_key, or a Secret of their own: apiKey is the name of any Secret that the plugin’s owner can read. See the sample manifests in plugins/websearch/.

The environment variable is listed in Configuration.

CI/CD Considerations

GitHub repository secret. Both workflows read the key from the GitHub Actions repository secret TAVILY_API_KEY. Add it in the repository’s Settings > Secrets and variables > Actions. It is never committed: neither values.yaml nor any manifest contains the key.

Tests (.github/workflows/test.yml). The workflow passes TAVILY_API_KEY to the test containers’ .env, with the other API keys. The unit tests do not call Tavily: they serve the Tavily API from a fake web host, and create a test Secret, so they pass without the GitHub secret.

Deployments (.github/workflows/deploy.yml). The workflow passes the GitHub secret to the tavily-api-key input of .github/actions/deploy, which sets the Helm value env.SMARTER_TAVILY_API_KEY. The chart’s init Job, templates/job-init.yaml, is a Helm post-install and post-upgrade hook, so every deployment runs initialize_platform, which creates or updates the Secret, and applies the sample plugins. Consequently:

  • Adding the key to an existing installation takes effect on the next deployment.

  • Rotating the key: update the GitHub secret, and deploy. The Secret is updated in place.

  • A deployment without the key completes, but the init Job logs that the tavily_api_key Secret was not created, and that smarter_project_websearch could not be applied. When the GitHub secret is not set, the deploy action passes no value, and Helm falls back to the values.yaml placeholder, which the init command recognizes and ignores.

  • Every environment that uses a Tavily WebsearchPlugin needs the key: local, alpha, beta and production. Each may use its own Tavily key, for separate usage and billing.

Cost and Limits

Tavily bills by API credits, and offers a free plan with a monthly allowance of credits; see the pricing on tavily.com. Smarter keeps usage low:

  • every search uses the basic search depth, Tavily’s least expensive.

  • results are cached for the plugin’s cacheTtl. smarter_project_websearch caches them for a day, because information about the project changes slowly.

  • only search calls Tavily. Reading a web page does not.

Monitor usage in the Tavily dashboard. When Tavily refuses a search, for example because the key is invalid or out of credits, the WebsearchPlugin returns an error to the LLM instead of search results, and sends the websearch_failed signal.

Troubleshooting

the web search api key Secret tavily_api_key does not exist, or is not accessible

The plugin was applied before the Secret existed, or by a user who cannot read it. Set TAVILY_API_KEY, run manage.py initialize_providers, and apply the plugin again.

Plugin smarter_project_websearch not found for account ...

An LLMClient that names the plugin was applied, but the plugin was not, almost always because of the missing Secret above. Fix the Secret, apply the plugin again, e.g. with manage.py load_from_github --include_kind WebsearchPlugin, and apply the LLMClient again.

TAVILY_API_KEY is not set, and SMARTER_TAVILY_API_KEY in the [API KEYS NOT SET] console error

The init command found no key, or only a placeholder. Set the environment variable, or, in a deployment, the GitHub secret TAVILY_API_KEY.

Previous Next

© Copyright 2023 - 2026 Lawrence P. McDaniel. The Smarter Project. Last updated November-2026.

Built with Sphinx using a theme provided by Read the Docs.