Skip to main content
Find answers to the most commonly asked questions about NOMOS. Can’t find what you’re looking for? Join our Discord community or open an issue.

​
Getting Started

NOMOS is a framework for building auditable AI agents with structured, multi-step workflows. Unlike black-box AI solutions, NOMOS provides transparency and control over your agent’s decision-making process, making it ideal for production environments where reliability and auditability are crucial.
Key differentiators include:
  • Auditability: Every decision and step is traceable and logged
  • Structured Workflows: Define clear, multi-step processes instead of single prompts
  • Provider Agnostic: Works with OpenAI, Anthropic, Google, Mistral, Ollama, and more
  • Production Ready: Built-in error handling, retries, and monitoring
  • Playground: No-code interface for rapid prototyping
Not necessarily! You can use NOMOS in several ways:
  • Playground: No-code drag-and-drop interface
  • YAML Configuration: Declarative configuration files
  • Python API: Full programmatic control for advanced use cases
  • CLI: Command-line interface for quick setup and deployment
  • Python: 3.8 or higher
  • Memory: Minimum 512MB RAM, 2GB+ recommended for complex agents
  • Storage: 100MB for basic installation, more for models and data
  • Network: Internet connection for LLM API calls (unless using local models)
  • OS: Windows, macOS, or Linux

​
Installation & Setup

Install using pip with your preferred LLM provider:
# Basic installation
pip install nomos

# With OpenAI support
pip install nomos[openai]

# With multiple providers
pip install nomos[openai,anthropic,google]

# All providers
pip install nomos[all]
Common solutions:
  • Ensure you installed the correct extras: pip install nomos[openai]
  • Check Python version: python --version (must be 3.8+)
  • Try upgrading pip: pip install --upgrade pip
  • Use virtual environment to avoid conflicts
  • Check for conflicting package versions
Set environment variables for your LLM providers:
# OpenAI
export OPENAI_API_KEY="your-key-here"

# Anthropic
export ANTHROPIC_API_KEY="your-key-here"

# Google
export GOOGLE_API_KEY="your-key-here"

# Mistral
export MISTRAL_API_KEY="your-key-here"
Or create a .env file in your project directory.
Yes! Use Ollama for local models:
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.3

# Use in NOMOS
pip install nomos[ollama]

​
LLM Providers & Models

NOMOS supports:
  • OpenAI: GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo
  • Anthropic: Claude 3.5 Sonnet, Haiku, Opus
  • Google: Gemini 2.0 Flash, Gemini 1.5 Pro/Flash
  • Mistral: Large, Medium, Small, Ministral
  • Ollama: Local models (Llama, Qwen, Codestral, etc.)
  • HuggingFace: Open source models via API
Depends on your use case:
  • Production: GPT-4o, Claude 3.5 Sonnet, Gemini 2.0 Flash
  • Development: GPT-4o-mini, Claude 3.5 Haiku, Mistral Small
  • Cost-sensitive: Ollama (local), GPT-4o-mini, Mistral Small
  • Privacy: Ollama (local models)
  • Coding: Claude 3.5 Sonnet, GPT-4o, Codestral
Yes! NOMOS provides a unified interface. Change providers by updating your configuration:
# Switch from OpenAI to Anthropic
llm:
  provider: anthropic  # was: openai
  model: claude-3-5-sonnet-20241022  # was: gpt-4o-mini
NOMOS includes built-in retry mechanisms:
llm:
  provider: openai
  model: gpt-4o-mini
  max_retries: 3
  retry_delay: 1.0

# Or use multiple providers as fallbacks
fallback_llms:
  - provider: openai
    model: gpt-4o-mini
  - provider: anthropic
    model: claude-3-5-haiku-20241022

​
Development & Configuration

  • YAML: Declarative, version-controlled, easier for non-programmers
  • Python: Programmatic control, dynamic behavior, custom logic
You can use both together - YAML for structure, Python for custom functions.
Several debugging options:
# Enable verbose logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Use debug mode
agent = Agent.from_yaml("config.yaml", debug=True)

# Trace execution
result = agent.run("input", trace=True)
print(result.trace)
Absolutely! Define custom tools:
from nomos.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    # Your implementation
    return f"Weather in {city}: Sunny, 72°F"

agent = Agent(
    name="weather-agent",
    tools=[get_weather]
)
Best practices:
  • Use environment variables for API keys
  • Implement data redaction in logging
  • Use local models for sensitive data
  • Configure memory retention policies
  • Implement custom data filters

​
Deployment & Production

Multiple deployment options:
# Docker
docker run -d chandralegend/nomos-base:latest

# Cloud platforms (Heroku, AWS, GCP, Azure)
nomos deploy --platform heroku

# Local server
nomos serve --host 0.0.0.0 --port 8000
Scaling strategies:
  • Horizontal: Multiple agent instances behind load balancer
  • Vertical: Increase CPU/memory for complex agents
  • Redis: Shared state and session management
  • PostgreSQL: Persistent storage for conversations
  • Queue Systems: Async processing with Celery/RQ
Built-in monitoring features:
  • Structured logging with trace IDs
  • Metrics collection (response time, error rates)
  • Health check endpoints
  • Integration with Prometheus/Grafana
  • Custom analytics hooks
Error handling strategies:
# Automatic retries
max_errors: 3
error_handling: retry_with_backoff

# Fallback responses
fallback_response: "I'm sorry, I'm experiencing technical difficulties."

# Error notifications
error_webhook: "https://your-monitoring-system.com/webhook"

​
Performance & Optimization

Optimization tips:
  • Use faster models (GPT-4o-mini vs GPT-4o)
  • Implement response caching
  • Reduce prompt length
  • Use streaming responses
  • Optimize tool execution
  • Consider local models for simple tasks
Cost optimization strategies:
  • Choose appropriate model sizes
  • Implement intelligent caching
  • Use cheaper models for simple tasks
  • Set token limits
  • Batch similar requests
  • Use local models when possible
Memory management:
  • Configure conversation limits
  • Use summary-based memory for long conversations
  • Implement periodic cleanup
  • Monitor memory usage in production
  • Consider external storage for large datasets

​
Troubleshooting

Debugging checklist:
  1. Check API keys and model availability
  2. Verify prompt engineering and instructions
  3. Review tool configurations
  4. Check for rate limiting
  5. Examine logs for error messages
  6. Test with simpler inputs first
Common solutions:
  • Increase timeout settings
  • Use smaller, faster models
  • Optimize prompt length
  • Check network connectivity
  • Implement retry logic
  • Consider request batching
Platform-specific solutions:Windows:
  • Use WSL2 for better compatibility
  • Install Visual C++ Build Tools
  • Use conda instead of pip if issues persist
macOS:
  • Install Xcode Command Line Tools
  • Use Homebrew for dependencies
  • Check Python version from Homebrew
Linux:
  • Install development packages
  • Check Python and pip versions
  • Use virtual environments

​
Integration & Ecosystem

Yes! NOMOS provides multiple integration options:
  • REST API for web integration
  • Python library for direct integration
  • Webhooks for event-driven architecture
  • CLI for script automation
  • Docker containers for microservices
NOMOS supports various storage options:
  • Built-in SQLite for development
  • PostgreSQL for production
  • Redis for caching and sessions
  • Custom database connectors
  • File-based storage for simple use cases
Absolutely! NOMOS integrates well with:
  • Vector databases (Pinecone, Weaviate, Chroma)
  • ML frameworks (scikit-learn, PyTorch, TensorFlow)
  • Data processing (pandas, NumPy)
  • Web frameworks (FastAPI, Flask, Django)
  • Workflow orchestrators (Airflow, Prefect)

​
Community & Support

Multiple support channels:
  1. Documentation: Check our comprehensive guides
  2. GitHub Issues: For bugs and feature requests
  3. Discord: Real-time community chat
  4. GitHub Discussions: Q&A and general discussion
  5. Email: Direct contact with maintainers
Ways to contribute:
  • Report bugs and suggest features
  • Improve documentation
  • Submit code contributions
  • Help other users in Discord
  • Share your projects in the showcase
  • Write tutorials and blog posts
Yes! Check our roadmap:
  • GitHub milestones for release planning
  • Community voting on feature requests
  • Regular updates in Discord announcements
  • Quarterly roadmap reviews

​
Still Have Questions?

Join Discord

Chat with the community and get real-time help

GitHub Discussions

Ask questions and share ideas with other developers

Open an Issue

Report bugs or request new features

Email Support

Direct contact with the NOMOS team
This FAQ is continuously updated based on community questions. If you have a question that’s not covered here, please ask in our Discord or GitHub discussions!
⌘I