# navuluribalaji/nkit architecture

> Architecture diagram of the GitHub repository navuluribalaji/nkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/navuluribalaji/nkit
- Repository: https://github.com/navuluribalaji/nkit

## Overview

##### Project Type and Purpose
- This is a Python library (package) for building “agents” around large language models (LLMs).
- It provides an Agent façade that handles prompts, async/sync calls, built-in tools (web search, file I/O, time), logging, error handling, retries, and tool registration.

##### File Structure
- Top-level packages:
- nanoagents/ – the original internal implementation
- nkit/       – the public API with Agent, chain, memory, tools, utils
- Key modules:
- Agent orchestration: nbagents.py (Agent class, run/run_async)
- Chain logic: chain.py, chain/ directory (step sequencing)
- LLM adapter: llm_adapter.py (sync vs async LLM calls)
- Memory: memory.py, memory/ directory (context storage)
- Prompt: prompt.py (templates, formatting)
- Tools: tools.py, tools/ (Tool class, registry, built-ins)
- Utils: utils.py (helpers for async detection, retries, logging setup)
- Config/build files: pyproject.toml, .github/workflows/ci.yml, scripts/test_poetry.ps1

##### README Insights
- Core features: async support, built-in tools, logging, error handling, tool registry, agent configuration.
- Usage: Agent instantiation → run/run_async → LLM calls + tool calls → output.
- Dependencies: requests, aiohttp, asyncio, logging.

##### Components
a. Main Components
- Client/User (invokes Agent API)
- Agent (Agent class façade)
- Chain Manager (Chain class)
- Prompt Manager (Prompt templates)
- LLM Adapter (sync/async wrapper)
- Tool Registry & Built-in Tools
- Memory Store
- Logger (cross-cutting)
- External Services:
– LLM Service (OpenAI/other)
– DuckDuckGo API
– File System
b. Relationships & Data Flows
1. Client → Agent.run()/run_async()
2. Agent → Prompt Manager formats user query
3. Agent → Chain Manager drives multi-step reasoning
4. Chain → LLM Adapter → External LLM Service
5. Chain → Tool Registry → Specific Tool
- WebSearchTool → DuckDuckGo API
- FileTools → File System
- TimeTool → System clock
6. Chain/Agent → Memory Store (read/write context)
7. All components → Logger for events, errors, retries
8. Agent returns final output to Client
c. Architectural Patterns & Principles
- Facade Pattern: Agent class hides internal complexity
- Strategy/Adapter Pattern: LLM Adapter isolates sync vs async calls
- Registry Pattern: Tool registration and auto-discovery
- Chain of Responsibility: Chain Manager sequences LLM calls and tool calls
- Cross-cutting Concerns: Logging and error handling injected throughout
d. Key Technologies
- Python 3.9+ with asyncio
- requests / aiohttp for HTTP calls
- logging module for configurable logs
- pyproject.toml + poetry for packaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client(("Client/User")):::external

    %% Agent Facade
    subgraph "Agent Facade"
        Agent["Agent\n(nkit.nbagents.Agent)"]:::core
        PromptManager["Prompt Manager"]:::core
        ChainManager["Chain Manager"]:::core
        MemoryAccess["Memory Access"]:::core
        LoggerHook["Logger Hook"]:::util
    end

    %% Core Components
    llmAdapter["LLM Adapter"]:::core
    ToolRegistry["Tool Registry"]:::core
    BuiltinTools["Built-in Tools"]:::tools
    memoryStore["Memory Store"]:::data
    utils["Utilities"]:::util
    Logger["Logger"]:::util

    %% External Services
    llmService(("LLM Service")):::external
    duckAPI(("DuckDuckGo API")):::external
    fileSystem(("File System")):::external
    systemClock(("System Clock")):::external

    %% Client to Agent
    Client -->|"run/run_async"| Agent
    Agent -->|"format prompt"| PromptManager
    PromptManager -->|"formatted prompt"| ChainManager
    ChainManager -->|"llm call sync"| llmAdapter
    ChainManager ---|"llm call async"| llmAdapter
    llmAdapter -->|"request"| llmService
    llmService -->|"response"| llmAdapter
    llmAdapter -->|"response"| ChainManager

    ChainManager -->|"use memory"| MemoryAccess
    MemoryAccess -->|"read/write"| memoryStore
    memoryStore -->|"data"| MemoryAccess

    ChainManager -->|"call tool"| ToolRegistry
    ToolRegistry -->|"invoke"| BuiltinTools
    BuiltinTools -->|"web search"| duckAPI
    BuiltinTools -->|"file ops"| fileSystem
    BuiltinTools -->|"time"| systemClock

    Agent -->|"final output"| Client

    %% Cross-cutting Logging
    Agent -.-> Logger
    PromptManager -.-> Logger
    ChainManager -.-> Logger
    llmAdapter -.-> Logger
    ToolRegistry -.-> Logger
    BuiltinTools -.-> Logger
    MemoryAccess -.-> Logger
    utils -.-> Logger

    %% Utilities integration
    Agent -.-> utils
    ChainManager -.-> utils
    llmAdapter -.-> utils
    ToolRegistry -.-> utils

    %% Click Events
    click Agent "https://github.com/navuluribalaji/nkit/blob/main/nkit/nbagents.py"
    click ChainManager "https://github.com/navuluribalaji/nkit/blob/main/nkit/chain/__init__.py"
    click llmAdapter "https://github.com/navuluribalaji/nkit/blob/main/nkit/llm_adapter.py"
    click PromptManager "https://github.com/navuluribalaji/nkit/blob/main/nkit/prompt.py"
    click ToolRegistry "https://github.com/navuluribalaji/nkit/blob/main/nkit/tools/__init__.py"
    click BuiltinTools "https://github.com/navuluribalaji/nkit/blob/main/nkit/tools/builtin_tools.py"
    click memoryStore "https://github.com/navuluribalaji/nkit/blob/main/nkit/memory/__init__.py"
    click utils "https://github.com/navuluribalaji/nkit/blob/main/nkit/utils.py"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef tools fill:#ABEBC6,stroke:#1D8348,color:#0E3624
    classDef external fill:#F5CBA7,stroke:#C0392B,color:#78281F
    classDef util fill:#E5E7E9,stroke:#566573,color:#1B2631
    classDef data fill:#F9E79F,stroke:#B7950B,color:#7E5109
```
