lightmodel 0.2.0__tar.gz → 0.4.1__tar.gz

{lightmodel-0.2.0 → lightmodel-0.4.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Your Name
+Copyright (c) 2026 PlimbAI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

lightmodel-0.4.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include SKILL.md
+include documentation.md
+include LICENSE

{lightmodel-0.2.0/src/lightmodel.egg-info → lightmodel-0.4.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: lightmodel
-Version: 0.2.0
+Version: 0.4.1
 Summary: Ultra-light autonomous AI agents for any OpenAI-compatible API
-Author-email: Your Name <you@example.com>
+Author-email: PlimbAI <plimb.ai.contact@gmail.com>
 License-Expression: MIT
-Keywords: llm,ai,agent,openai,nvidia-nim,tool-calling
+Keywords: llm,ai,agent,openai,nvidia-nim,tool-calling,no-dependencies
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
@@ -20,10 +20,18 @@ Dynamic: license-file
 Ultra-light **autonomous AI agents** for any OpenAI-compatible API.
 No `smolagents`, no `litellm`, no `openai` — just `requests`.
 
+## Features
+
+- `LightModel`: HTTP client with automatic retry on transient errors
+- `Agent`: autonomous tool-calling loop with parallel tools and callbacks
+- Built-in tools: `web_search`, `visit_webpage`, `calculator`
+- Extensible: add a tool by subclassing `Tool`
+- Zero heavy dependencies
+
 ## Installation
 
     pip install lightmodel
-    pip install lightmodel[search]   # with beautifulsoup4 for web search
+    pip install lightmodel[search]   # with beautifulsoup4 for web tools
 
 ## Quick start
 
@@ -38,21 +46,47 @@ No `smolagents`, no `litellm`, no `openai` — just `requests`.
         model=model,
         tools=[SimpleDuckDuckGoSearchTool()],
         system_prompt="You are a helpful research assistant.",
+        max_steps=6,
+        verbose=True,
     )
     print(agent.run("What are the latest AI news in 2026?"))
 
+## Multi-turn conversation
+
+    print(agent.chat("Tell me more about the first result."))
+    print(agent.chat("Summarize in one sentence."))
+
 ## Custom tools
 
     from lightmodel import Tool
 
     class CalculatorTool(Tool):
         name = "calculator"
-        description = "Evaluate a basic arithmetic expression."
+        description = "Evaluate arithmetic."
         inputs = {"expression": {"type": "string", "description": "e.g. 2+2"}}
 
         def forward(self, expression):
             return str(eval(expression, {"__builtins__": {}}, {}))
 
+## Callbacks
+
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool()],
+        callbacks={
+            "on_step": lambda step, msg: print(f"step {step}"),
+            "on_tool_call": lambda name, args: print(f"→ {name}({args})"),
+            "on_tool_result": lambda name, result: print(f"← {result[:80]}"),
+            "on_final": lambda answer: print(f"✓ done"),
+            "on_error": lambda exc: print(f"✗ {exc}"),
+        },
+    )
+
+## Streaming
+
+    for chunk in model.stream_chat([{"role": "user", "content": "Hi"}]):
+        print(chunk, end="", flush=True)
+
 ## License
 
 MIT

lightmodel-0.4.1/README.md

@@ -0,0 +1,75 @@
+# LightModel
+
+Ultra-light **autonomous AI agents** for any OpenAI-compatible API.
+No `smolagents`, no `litellm`, no `openai` — just `requests`.
+
+## Features
+
+- `LightModel`: HTTP client with automatic retry on transient errors
+- `Agent`: autonomous tool-calling loop with parallel tools and callbacks
+- Built-in tools: `web_search`, `visit_webpage`, `calculator`
+- Extensible: add a tool by subclassing `Tool`
+- Zero heavy dependencies
+
+## Installation
+
+    pip install lightmodel
+    pip install lightmodel[search]   # with beautifulsoup4 for web tools
+
+## Quick start
+
+    from lightmodel import Agent, LightModel, SimpleDuckDuckGoSearchTool
+
+    model = LightModel(
+        model_id="meta/llama-3.3-70b-instruct",
+        api_base="https://integrate.api.nvidia.com/v1",
+        api_key="your_key",
+    )
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool()],
+        system_prompt="You are a helpful research assistant.",
+        max_steps=6,
+        verbose=True,
+    )
+    print(agent.run("What are the latest AI news in 2026?"))
+
+## Multi-turn conversation
+
+    print(agent.chat("Tell me more about the first result."))
+    print(agent.chat("Summarize in one sentence."))
+
+## Custom tools
+
+    from lightmodel import Tool
+
+    class CalculatorTool(Tool):
+        name = "calculator"
+        description = "Evaluate arithmetic."
+        inputs = {"expression": {"type": "string", "description": "e.g. 2+2"}}
+
+        def forward(self, expression):
+            return str(eval(expression, {"__builtins__": {}}, {}))
+
+## Callbacks
+
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool()],
+        callbacks={
+            "on_step": lambda step, msg: print(f"step {step}"),
+            "on_tool_call": lambda name, args: print(f"→ {name}({args})"),
+            "on_tool_result": lambda name, result: print(f"← {result[:80]}"),
+            "on_final": lambda answer: print(f"✓ done"),
+            "on_error": lambda exc: print(f"✗ {exc}"),
+        },
+    )
+
+## Streaming
+
+    for chunk in model.stream_chat([{"role": "user", "content": "Hi"}]):
+        print(chunk, end="", flush=True)
+
+## License
+
+MIT

lightmodel-0.4.1/SKILL.md

@@ -0,0 +1,183 @@
+# SKILL.md — LightModel for AI assistants
+
+> Audience: AI coding assistants. If you are an AI asked to build a tool or an
+> agent with lightmodel, read this first. It contains the minimal rules,
+> templates and common mistakes.
+
+## What is lightmodel?
+
+A ~400-line Python package providing:
+
+- LightModel: HTTP client for any OpenAI-compatible /chat/completions API.
+- Agent: autonomous tool-calling loop with retries, parallel tools, callbacks.
+- Tool: base class for tools.
+- @tool: decorator to build a tool from a plain function.
+- Built-ins: SimpleDuckDuckGoSearchTool, VisitWebpageTool, CalculatorTool.
+
+Dependencies: requests (mandatory), beautifulsoup4 (optional, for web tools).
+
+## Rule 1 — create a tool by subclassing Tool
+
+    from lightmodel import Tool
+
+    class MyTool(Tool):
+        name = "snake_case_name"
+        description = "One sentence describing what it does and when to use it."
+        inputs = {
+            "param_a": {"type": "string", "description": "..."},
+            "param_b": {"type": "integer", "description": "..."},
+        }
+
+        def forward(self, param_a, param_b=0):
+            return f"result as string"
+
+Valid type values: string, integer, number, boolean, array, object.
+
+## Rule 2 — never raise inside forward
+
+The return value is fed back to the LLM. If you raise, the agent crashes.
+
+    def forward(self, path):
+        try:
+            return open(path).read()[:3000]
+        except Exception as e:
+            return f"Error: {e}"
+
+## Rule 3 — description is a prompt
+
+The LLM reads description to decide whether to call the tool. Write it as an
+instruction.
+
+- Bad: "Search."
+- Good: "Search the web for current events. Do NOT use for math or code."
+
+## Rule 4 — inputs must be a dict of JSON-Schema-like specs
+
+    inputs = {
+        "query": {"type": "string", "description": "User search query"},
+        "limit": {"type": "integer", "description": "Max results (default 5)"},
+    }
+
+## Creating a tool from a function — @tool
+
+    from lightmodel import tool
+
+    @tool(name="add", description="Add two integers.")
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    agent = Agent(model=model, tools=[add])
+
+Types are inferred from annotations: int -> integer, float -> number,
+bool -> boolean.
+
+## Creating an agent — standard template
+
+    from lightmodel import Agent, LightModel, SimpleDuckDuckGoSearchTool
+
+    model = LightModel(
+        model_id="meta/llama-3.3-70b-instruct",
+        api_base="https://integrate.api.nvidia.com/v1",
+        api_key="VOTRE_CLE",
+        temperature=0.2,
+        max_tokens=4096,
+    )
+
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool()],
+        system_prompt="You are a helpful assistant.",
+        max_steps=8,
+        verbose=True,
+    )
+
+    print(agent.run("What are the latest AI news?"))
+
+## Multi-turn conversation
+
+    agent.run("Question 1?")     # fresh (clears history)
+    agent.chat("Follow-up?")     # continues
+    agent.chat("Another?")       # continues
+    agent.reset()                # clears history
+
+## Persistence
+
+    agent.save_session("session.json")
+    agent.load_session("session.json")
+
+## From a config dict
+
+    agent = Agent.from_config({
+        "model": {
+            "model_id": "meta/llama-3.3-70b-instruct",
+            "api_base": "https://integrate.api.nvidia.com/v1",
+            "api_key": "VOTRE_CLE",
+        },
+        "tools": [SimpleDuckDuckGoSearchTool()],
+        "system_prompt": "You are helpful.",
+        "max_steps": 8,
+    })
+
+## Callbacks
+
+    agent = Agent(
+        model=model,
+        tools=[...],
+        callbacks={
+            "on_step":        lambda step, msg: ...,
+            "on_tool_call":   lambda name, args: ...,
+            "on_tool_result": lambda name, result: ...,
+            "on_final":       lambda answer: ...,
+            "on_error":       lambda exc: ...,
+        },
+    )
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| name = "my tool" | use "my_tool" (snake_case) |
+| def forward(self) with inputs defined | must accept each input as a kwarg |
+| Raising in forward | return an error string |
+| Empty description | write a clear one-sentence purpose |
+| Committing api_key | read from env or config file, never commit |
+| max_steps=1 | use at least 4 to 8 for tool loops |
+
+## Complete end-to-end example
+
+    from lightmodel import Agent, LightModel, Tool, SimpleDuckDuckGoSearchTool
+
+    class WeatherTool(Tool):
+        name = "get_weather"
+        description = "Get current weather for a city. Use for weather questions."
+        inputs = {"city": {"type": "string", "description": "City name"}}
+
+        _DATA = {"Paris": 18, "Tokyo": 24, "New York": 15}
+
+        def forward(self, city):
+            if city not in self._DATA:
+                return f"Unknown city: {city}"
+            return f"{city}: {self._DATA[city]} C"
+
+    model = LightModel(
+        model_id="meta/llama-3.3-70b-instruct",
+        api_base="https://integrate.api.nvidia.com/v1",
+        api_key="VOTRE_CLE",
+        temperature=0.2,
+        max_tokens=4096,
+    )
+
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool(), WeatherTool()],
+        system_prompt="You are a concise assistant.",
+        max_steps=8,
+        verbose=True,
+    )
+
+    print(agent.run("Weather in Paris and Tokyo, and any AI news today?"))
+
+## References
+
+- Full human documentation: documentation.md
+- Source: PyPI page of lightmodel

lightmodel-0.4.1/documentation.md

@@ -0,0 +1,307 @@
+# LightModel — Documentation
+
+Version 0.4.1 · Author: PlimbAI · License: MIT
+
+Ultra-light autonomous AI agents for any OpenAI-compatible API.
+No smolagents, no litellm, no openai — just requests.
+
+## Table of contents
+
+1. Installation
+2. Quick start
+3. LightModel (client)
+4. Tool (base class)
+5. @tool decorator
+6. Agent
+7. Built-in tools
+8. Callbacks
+9. Persistence
+10. Streaming
+11. Error handling
+12. Compatibility matrix
+13. FAQ
+
+## Installation
+
+    pip install lightmodel
+    pip install lightmodel[search]
+
+Requirements: Python 3.9+, requests. Web tools require beautifulsoup4.
+
+## Quick start
+
+    from lightmodel import Agent, LightModel, SimpleDuckDuckGoSearchTool
+
+    model = LightModel(
+        model_id="meta/llama-3.3-70b-instruct",
+        api_base="https://integrate.api.nvidia.com/v1",
+        api_key="YOUR_KEY",
+        temperature=0.2,
+        max_tokens=4096,
+    )
+
+    agent = Agent(
+        model=model,
+        tools=[SimpleDuckDuckGoSearchTool()],
+        system_prompt="You are a concise research assistant.",
+        max_steps=8,
+        verbose=True,
+    )
+
+    print(agent.run("What are the latest AI news in 2026?"))
+
+## LightModel (client)
+
+Low-level HTTP client. Use it directly for full control, or pass it to an Agent.
+
+### Constructor
+
+    LightModel(
+        model_id,
+        api_base,
+        api_key="not-needed",
+        temperature=0.7,
+        max_tokens=2048,
+        timeout=120,
+        max_retries=3,
+        retry_backoff=2.0,
+        extra=None,
+        headers=None,
+    )
+
+### Methods
+
+#### chat(messages, tools=None, **overrides) -> dict
+
+Sends messages and returns the assistant message dict. Retries automatically
+on transient errors.
+
+    reply = model.chat([{"role": "user", "content": "Hello"}])
+    print(reply["content"])
+
+#### stream_chat(messages, tools=None, **overrides) -> Iterator[str]
+
+Yields content chunks as they arrive (Server-Sent Events).
+
+    for chunk in model.stream_chat([{"role": "user", "content": "Write a haiku"}]):
+        print(chunk, end="", flush=True)
+
+#### list_models() -> list[str]
+
+Best-effort listing of available models via GET /models.
+
+## Tool (base class)
+
+Subclass and override forward(). Four class attributes are required.
+
+    from lightmodel import Tool
+
+    class MyTool(Tool):
+        name = "my_tool"
+        description = "What this tool does and when to use it."
+        inputs = {
+            "query": {"type": "string", "description": "The search query"},
+        }
+
+        def forward(self, query):
+            return f"Result for {query}"
+
+### Attributes
+
+| Attribute | Type | Required | Purpose |
+|---|---|---|---|
+| name | str | yes | Identifier the LLM uses to call the tool |
+| description | str | yes | Prompt used by the LLM to decide when to use |
+| inputs | dict | yes | JSON Schema-like specs per parameter |
+| forward | method | yes | Execution logic, must return a string |
+
+Valid input types: string, integer, number, boolean, array, object.
+
+## @tool decorator
+
+Quickly turn a Python function into a Tool.
+
+    from lightmodel import tool
+
+    @tool(name="add", description="Add two integers.")
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    print(add.name)
+    print(add.forward(a=2, b=3))
+
+Type hints are used to infer JSON Schema types: int -> integer,
+float -> number, bool -> boolean, otherwise string.
+
+## Agent
+
+Autonomous tool-calling loop with retries, parallel execution, history.
+
+### Constructor
+
+    Agent(
+        model,
+        tools=None,
+        system_prompt=None,
+        max_steps=10,
+        verbose=False,
+        parallel_tools=True,
+        callbacks=None,
+        raise_on_max_steps=False,
+    )
+
+### Methods
+
+#### run(task, reset=True) -> str
+
+Fresh execution. Clears history if reset=True.
+
+#### chat(message, reset=False) -> str
+
+Continues conversation. History preserved.
+
+#### reset()
+
+Clears messages but keeps the system prompt.
+
+#### save_session(path)
+
+Persists messages and system prompt to a JSON file.
+
+#### load_session(path) -> bool
+
+Restores messages from a JSON file.
+
+#### Agent.from_config(dict) -> Agent
+
+    agent = Agent.from_config({
+        "model": {
+            "model_id": "meta/llama-3.3-70b-instruct",
+            "api_base": "https://integrate.api.nvidia.com/v1",
+            "api_key": "YOUR_KEY",
+        },
+        "tools": [MyTool()],
+        "system_prompt": "You are helpful.",
+        "max_steps": 8,
+    })
+
+## Built-in tools
+
+### SimpleDuckDuckGoSearchTool()
+
+Scrapes DuckDuckGo HTML (top 5 results). No API key.
+
+Input: query (string). Output: results as text.
+
+### VisitWebpageTool(max_chars=3000)
+
+Fetches a URL, strips scripts/styles/nav, returns main text truncated.
+
+Input: url (string). Output: page text.
+
+### CalculatorTool()
+
+Safely evaluates basic arithmetic expressions.
+
+Input: expression (string). Output: result.
+
+## Callbacks
+
+    agent = Agent(
+        model=model,
+        tools=[...],
+        callbacks={
+            "on_step":        lambda step, msg: print(f"step {step}"),
+            "on_tool_call":   lambda name, args: print(f"-> {name}({args})"),
+            "on_tool_result": lambda name, result: print(f"<- {result[:80]}"),
+            "on_final":       lambda answer: print(f"done ({len(answer)} chars)"),
+            "on_error":       lambda exc: print(f"err {exc}"),
+        },
+    )
+
+Callbacks that raise are logged and ignored. They never break the agent.
+
+## Persistence
+
+    agent.save_session("session.json")
+
+    agent.load_session("session.json")
+    agent.chat("Continue where we left off?")
+
+Format: a JSON object with messages and system_prompt.
+
+## Streaming
+
+    for chunk in model.stream_chat([{"role": "user", "content": "Write a haiku"}]):
+        print(chunk, end="", flush=True)
+
+Note: Agent.run() does not stream. Use model.stream_chat() directly.
+
+## Error handling
+
+Custom exceptions in lightmodel.exceptions:
+
+| Exception | When |
+|---|---|
+| LightModelError | Base class |
+| APIError | HTTP 4xx/5xx (has .status and .body attributes) |
+| ToolError | A tool failed in forward() (returned as string by default) |
+| MaxStepsError | max_steps reached without final answer |
+
+Automatic retries cover 429, 500, 502, 503, 504 with exponential backoff.
+
+    from lightmodel import APIError
+
+    try:
+        agent.run("...")
+    except APIError as e:
+        print(f"Status {e.status}: {e}")
+
+## Compatibility matrix
+
+Works with any OpenAI-compatible API that supports tool calling.
+
+| Provider | Base URL | Model example |
+|---|---|---|
+| NVIDIA NIM | https://integrate.api.nvidia.com/v1 | meta/llama-3.3-70b-instruct |
+| Ollama | http://localhost:11434/v1 | llama3.3 |
+| vLLM | http://localhost:8000/v1 | whatever is served |
+| LM Studio | http://localhost:1234/v1 | whatever is served |
+| Groq | https://api.groq.com/openai/v1 | llama-3.3-70b-versatile |
+| OpenRouter | https://openrouter.ai/api/v1 | meta-llama/llama-3.3-70b-instruct |
+| Together | https://api.together.xyz/v1 | meta-llama/Llama-3.3-70B-Instruct-Turbo |
+| DeepSeek | https://api.deepseek.com/v1 | deepseek-chat |
+| OpenAI | https://api.openai.com/v1 | gpt-4o-mini |
+
+Required by the model: support for the OpenAI tools parameter and tool_calls
+in responses.
+
+## FAQ
+
+Q: Does it work without smolagents?
+A: Yes. lightmodel has zero dependency on smolagents, openai, or litellm.
+
+Q: Does it compile Rust?
+A: No. Only requests (mandatory) and beautifulsoup4 (optional).
+
+Q: Does it run on Termux or Android?
+A: Yes. No native extension needed.
+
+Q: Can I use a local model?
+A: Yes. Point api_base to your vLLM, Ollama or LM Studio server.
+
+Q: Can I have multiple agents in one process?
+A: Yes. Each Agent has its own history. Share the same LightModel if you want.
+
+Q: How do I add memory?
+A: Write a Tool that reads or writes a file, or use save_session and load_session.
+
+Q: How do I stream from Agent.run()?
+A: Not currently. Use model.stream_chat() directly.
+
+Q: What is the [search] extra for?
+A: It installs beautifulsoup4, needed by the web tools.
+
+## License
+
+MIT (c) 2026 PlimbAI

{lightmodel-0.2.0 → lightmodel-0.4.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lightmodel"
-version = "0.2.0"
+version = "0.4.1"
 description = "Ultra-light autonomous AI agents for any OpenAI-compatible API"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
-authors = [{name = "Your Name", email = "you@example.com"}]
-keywords = ["llm", "ai", "agent", "openai", "nvidia-nim", "tool-calling"]
+authors = [{name = "PlimbAI", email = "plimb.ai.contact@gmail.com"}]
+keywords = ["llm", "ai", "agent", "openai", "nvidia-nim", "tool-calling", "no-dependencies"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -22,3 +22,6 @@ search = ["beautifulsoup4>=4.12"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+lightmodel = ["SKILL.md", "documentation.md"]