ollama-client 0.2.5 → 0.2.6

data/lib/ollama/personas.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Persona system for explicit, contextual personalization.
+  #
+  # Personas are NOT baked into models or server config. They are injected
+  # explicitly at the system/prompt layer, allowing you to:
+  #
+  # - Use compressed versions for schema-based agent work (deterministic)
+  # - Use minimal chat-safe versions for chat/streaming UI work (human-facing)
+  # - Switch personas per task without model changes
+  # - Maintain multiple personas for different contexts
+  #
+  # This is architecturally superior to ChatGPT's implicit global personalization.
+  #
+  # ## Persona Variants
+  #
+  # Each persona has two variants:
+  #
+  # ### Agent Variants (`:agent`)
+  # - Designed for `/api/generate` with JSON schemas
+  # - Minimal, directive, non-chatty
+  # - Preserves determinism in structured outputs
+  # - No markdown, no explanations, no extra fields
+  # - Use with Planner, structured extraction, decision engines
+  #
+  # ### Chat Variants (`:chat`)
+  # - Designed for `/api/chat` with ChatSession
+  # - Minimal, chat-safe, allows explanations
+  # - Explicitly disclaims authority and side effects
+  # - Allows streaming and markdown for presentation
+  # - Use ONLY for human-facing chat interfaces
+  # - Must NEVER be used for schema-based agent work
+  #
+  # ## Critical Separation
+  #
+  # - Agent personas: `/api/generate` + schemas = deterministic reasoning
+  # - Chat personas: `/api/chat` + humans = explanatory conversation
+  #
+  # Mixing them breaks determinism and safety boundaries.
+  # rubocop:disable Metrics/ModuleLength
+  module Personas
+    # Minimal agent-safe persona for schema-based planning and structured outputs.
+    #
+    # This version is:
+    # - Minimal and direct (no verbosity)
+    # - Focused on correctness and invariants
+    # - No chatty behavior or markdown drift
+    # - Preserves determinism in structured outputs
+    # - Designed for /api/generate, schema-validated, deterministic workflows
+    #
+    # This prompt turns the LLM into a deterministic reasoning subroutine,
+    # not a conversational partner. Use for planners, routers, decision engines.
+    ARCHITECT_AGENT = <<~PROMPT
+      You are acting as a senior software architect and system designer.
+
+      Operating rules:
+      - Optimize for correctness and robustness first.
+      - Make explicit decisions; do not hedge.
+      - Do not invent data, APIs, or system behavior.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume side effects; propose intent only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer simple, explicit solutions over clever ones.
+
+      Focus areas:
+      - System boundaries and invariants
+      - Failure modes and edge cases
+      - Production-grade architecture decisions
+    PROMPT
+
+    # Minimal chat-safe persona for human-facing chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    ARCHITECT_CHAT = <<~PROMPT
+      You are a senior software architect and systems engineer.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain reasoning when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent APIs, data, or system behavior.
+      - If information is missing, say so explicitly.
+      - Prefer concrete examples over abstract theory.
+
+      Boundaries:
+      - You do not execute actions or side effects.
+      - You provide explanations, guidance, and reasoning only.
+      - Decisions that affect systems must be validated externally.
+
+      Tone:
+      - Professional, calm, and no-nonsense.
+      - Assume the user has strong technical background.
+    PROMPT
+
+    # Minimal agent-safe persona for trading/analysis work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for market analysis, risk assessment, and trading decisions.
+    TRADING_AGENT = <<~PROMPT
+      You are acting as a quantitative trading system analyst.
+
+      Operating rules:
+      - Optimize for data accuracy and risk assessment first.
+      - Make explicit decisions based on provided data only.
+      - Do not invent market data, prices, or indicators.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume market behavior; base analysis on data only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit risk statements over predictions.
+
+      Focus areas:
+      - Risk management and edge cases
+      - Data-driven analysis without emotional bias
+      - Objective assessment of market conditions
+    PROMPT
+
+    # Minimal chat-safe persona for trading chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    TRADING_CHAT = <<~PROMPT
+      You are a quantitative trading system analyst.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and data-focused.
+      - Explain analysis when it helps understanding.
+      - Avoid predictions, guarantees, or emotional language.
+      - Do not invent market data, prices, or indicators.
+      - If information is missing, say so explicitly.
+      - Prefer concrete data examples over abstract theory.
+
+      Boundaries:
+      - You do not execute trades or market actions.
+      - You provide analysis, guidance, and reasoning only.
+      - Trading decisions must be validated externally.
+
+      Tone:
+      - Professional, objective, and risk-aware.
+      - Assume the user understands market fundamentals.
+    PROMPT
+
+    # Minimal agent-safe persona for code review work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for code quality assessment and refactoring decisions.
+    REVIEWER_AGENT = <<~PROMPT
+      You are acting as a code review assistant focused on maintainability and correctness.
+
+      Operating rules:
+      - Optimize for code clarity and maintainability first.
+      - Make explicit decisions about code quality issues.
+      - Do not invent code patterns or assume implementation details.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume intent; identify issues from code structure only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit refactoring suggestions over general advice.
+
+      Focus areas:
+      - Unclear names, long methods, hidden responsibilities
+      - Single responsibility and testability
+      - Unnecessary complexity and code smells
+    PROMPT
+
+    # Minimal chat-safe persona for code review chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    REVIEWER_CHAT = <<~PROMPT
+      You are a code review assistant focused on maintainability and correctness.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain code quality issues when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent code patterns or assume implementation details.
+      - If information is missing, say so explicitly.
+      - Prefer concrete refactoring examples over abstract principles.
+
+      Boundaries:
+      - You do not modify code or execute refactorings.
+      - You provide review, guidance, and suggestions only.
+      - Code changes must be validated externally.
+
+      Tone:
+      - Professional, constructive, and no-nonsense.
+      - Assume the user values code quality and maintainability.
+    PROMPT
+
+    # Registry of all available personas.
+    #
+    # Each persona has two variants:
+    # - `:agent` - Minimal version for schema-based agent work (/api/generate)
+    # - `:chat` - Minimal chat-safe version for human-facing interfaces (/api/chat)
+    #
+    # IMPORTANT: Chat personas must NEVER be used for schema-based agent work.
+    # They are designed for ChatSession and streaming only.
+    REGISTRY = {
+      architect: {
+        agent: ARCHITECT_AGENT,
+        chat: ARCHITECT_CHAT
+      },
+      trading: {
+        agent: TRADING_AGENT,
+        chat: TRADING_CHAT
+      },
+      reviewer: {
+        agent: REVIEWER_AGENT,
+        chat: REVIEWER_CHAT
+      }
+    }.freeze
+
+    # Get a persona by name and variant.
+    #
+    # @param name [Symbol] Persona name (:architect, :trading, :reviewer)
+    # @param variant [Symbol] Variant (:agent or :chat)
+    # @return [String, nil] Persona prompt text, or nil if not found
+    #
+    # @example
+    #   Personas.get(:architect, :agent)  # => Compressed agent version
+    #   Personas.get(:architect, :chat)    # => Full chat version
+    def self.get(name, variant: :agent)
+      REGISTRY.dig(name.to_sym, variant.to_sym)
+    end
+
+    # List all available persona names.
+    #
+    # @return [Array<Symbol>] List of persona names
+    def self.available
+      REGISTRY.keys
+    end
+
+    # Check if a persona exists.
+    #
+    # @param name [Symbol, String] Persona name
+    # @return [Boolean] True if persona exists
+    def self.exists?(name)
+      REGISTRY.key?(name.to_sym)
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/ollama/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ollama
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

data/lib/ollama_client.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Load .env file if available (.env takes precedence over shell environment variables)
+require "dotenv"
+Dotenv.overload
+
+require_relative "ollama/version"
 require_relative "ollama/config"
 require_relative "ollama/errors"
 require_relative "ollama/schema_validator"
@@ -9,9 +14,11 @@ require_relative "ollama/tool"
 require_relative "ollama/client"
 require_relative "ollama/document_loader"
 require_relative "ollama/streaming_observer"
+require_relative "ollama/chat_session"
 require_relative "ollama/agent/messages"
 require_relative "ollama/agent/planner"
 require_relative "ollama/agent/executor"
+require_relative "ollama/personas"
 
 # Main entry point for OllamaClient gem
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ollama-client
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-21 00:00:00.000000000 Z
+date: 2026-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -60,7 +60,6 @@ description: A production-ready, agent-first Ruby client for the Ollama API with
 email:
 - shubhamtaywade82@gmail.com
 executables:
-- dhan_console
 - ollama-client
 extensions: []
 extra_rdoc_files: []
@@ -73,66 +72,32 @@ files:
 - Rakefile
 - docs/CLOUD.md
 - docs/CONSOLE_IMPROVEMENTS.md
+- docs/EXAMPLE_REORGANIZATION.md
 - docs/FEATURES_ADDED.md
+- docs/GETTING_STARTED.md
 - docs/HANDLERS_ANALYSIS.md
+- docs/INTEGRATION_TESTING.md
+- docs/NEXT_STEPS_SUMMARY.md
+- docs/PERSONAS.md
 - docs/PRODUCTION_FIXES.md
+- docs/QUICK_START.md
 - docs/README.md
 - docs/RELEASE_GUIDE.md
 - docs/SCHEMA_FIXES.md
 - docs/TESTING.md
+- docs/TEST_CHECKLIST.md
 - docs/TEST_UPDATES.md
 - docs/ruby_guide.md
 - examples/README.md
-- examples/advanced_complex_schemas.rb
-- examples/advanced_edge_cases.rb
-- examples/advanced_error_handling.rb
-- examples/advanced_multi_step_agent.rb
-- examples/advanced_performance_testing.rb
-- examples/chat_console.rb
-- examples/complete_workflow.rb
-- examples/dhan_console.rb
-- examples/dhanhq/README.md
-- examples/dhanhq/agents/base_agent.rb
-- examples/dhanhq/agents/data_agent.rb
-- examples/dhanhq/agents/orchestrator_agent.rb
-- examples/dhanhq/agents/technical_analysis_agent.rb
-- examples/dhanhq/agents/trading_agent.rb
-- examples/dhanhq/analysis/market_structure.rb
-- examples/dhanhq/analysis/pattern_recognizer.rb
-- examples/dhanhq/analysis/trend_analyzer.rb
-- examples/dhanhq/builders/market_context_builder.rb
-- examples/dhanhq/dhanhq_agent.rb
-- examples/dhanhq/indicators/technical_indicators.rb
-- examples/dhanhq/scanners/intraday_options_scanner.rb
-- examples/dhanhq/scanners/swing_scanner.rb
-- examples/dhanhq/schemas/agent_schemas.rb
-- examples/dhanhq/services/base_service.rb
-- examples/dhanhq/services/data_service.rb
-- examples/dhanhq/services/trading_service.rb
-- examples/dhanhq/technical_analysis_agentic_runner.rb
-- examples/dhanhq/technical_analysis_runner.rb
-- examples/dhanhq/test_tool_calling.rb
-- examples/dhanhq/test_tool_calling_verbose.rb
-- examples/dhanhq/utils/instrument_helper.rb
-- examples/dhanhq/utils/parameter_cleaner.rb
-- examples/dhanhq/utils/parameter_normalizer.rb
-- examples/dhanhq/utils/rate_limiter.rb
-- examples/dhanhq/utils/trading_parameter_normalizer.rb
-- examples/dhanhq_agent.rb
-- examples/dhanhq_tools.rb
-- examples/multi_step_agent_with_external_data.rb
-- examples/structured_outputs_chat.rb
-- examples/structured_tools.rb
-- examples/test_dhanhq_tool_calling.rb
-- examples/test_tool_calling.rb
-- examples/tool_calling_direct.rb
-- examples/tool_calling_pattern.rb
+- examples/basic_chat.rb
+- examples/basic_generate.rb
+- examples/tool_calling_parsing.rb
 - examples/tool_dto_example.rb
-- exe/dhan_console
 - exe/ollama-client
 - lib/ollama/agent/executor.rb
 - lib/ollama/agent/messages.rb
 - lib/ollama/agent/planner.rb
+- lib/ollama/chat_session.rb
 - lib/ollama/client.rb
 - lib/ollama/config.rb
 - lib/ollama/document_loader.rb
@@ -140,6 +105,7 @@ files:
 - lib/ollama/embeddings.rb
 - lib/ollama/errors.rb
 - lib/ollama/options.rb
+- lib/ollama/personas.rb
 - lib/ollama/response.rb
 - lib/ollama/schema_validator.rb
 - lib/ollama/schemas/base.json