akasha
akasha is a Python toolkit for document question answering, image understanding, image generation and editing, retrieval-augmented generation (RAG), native tool-calling agents, summaries, and long-term semantic memory.
It provides one consistent interface for remote and local model workflows while keeping provider-specific integrations behind model aliases such as openai:, gemini:, anthropic:, and ollama:.
- manual: https://iii-org.github.io/akasha/
- Current package version:
1.7.3
What akasha provides
Chat / QA — Use akasha.ask() to ask a model a question, optionally with documents or web information.
Vision — Use asker.vision() to ask questions about one or more images and receive a text answer.
Image generation — Use akasha.gen_image() to generate a new image from a text prompt.
Image editing — Use akasha.edit_image() to remove, add, or change content in an existing image.
Agents — Use akasha.agents() for LangChain-native tool calling, streaming, thinking events, Skills, and MCP tools.
RAG — Use akasha.RAG() to load documents, create embeddings, search Chroma, and generate an answer.
Summaries — Use akasha.summary() to summarize text, files, or URLs with map_reduce or refine.
Long-term memory — Use MemoryManager to store and retrieve semantic memories with Chroma.
Installation
Python 3.11 or 3.12 is recommended.
Lightweight installation
Use light for remote chat models and remote embeddings:
uv venv --python 3.11
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
uv pip install "akasha-terminal[light]"
light keeps Chroma-backed RAG and memory workflows, but does not include the local HuggingFace / Torch model stack.
Full installation
Use full when you need local embeddings, local HuggingFace models, local Llama/GPTQ models, reranking, or BERTScore:
uv pip install "akasha-terminal[full]"
The practical difference is:
| Installation | Chat models | Embeddings | Vector store | Local ML / rerank |
|---|---|---|---|---|
light |
Remote providers | Remote APIs | Local Chroma | No |
full |
Remote and local providers | Remote and local | Local Chroma | Yes |
light does not include Torch, Transformers, Sentence-Transformers, or onnxruntime; these local-model dependencies are part of full.
Editable installation for development
uv pip install -e ".[light,dev]"
For the complete local-model stack:
uv pip install -e ".[full,dev]"
Configure a model provider
Set provider credentials in the environment or in a .env file. Never commit .env files or API keys.
OPENAI_API_KEY=your_key
GEMINI_API_KEY=your_key
ANTHROPIC_API_KEY=your_key
# Optional Azure OpenAI-compatible endpoint
AZURE_OPENAI_API_KEY=your_key
AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com/
# Optional Ollama endpoint
OLLAMA_API_BASE=http://localhost:11434
Supported chat model aliases include:
openai:gpt-4o
gemini:gemini-2.5-flash
anthropic:claude-3-5-sonnet-latest
ollama:qwen3:8b
azure:your-deployment-name
Ollama can also target another host:
ollama:http://192.168.1.10:11434@qwen3:8b
The same public interfaces accept an already configured LangChain ChatModel when provider-specific configuration is needed.
Quick start: chat
import akasha
qa = akasha.ask(model="gemini:gemini-2.5-flash")
answer = qa("What is retrieval-augmented generation?")
print(answer)
ask(stream=False) returns a final str.
Quick start: vision and image editing
Use vision() for image understanding. It accepts an image and a question, then returns text:
import akasha
qa = akasha.ask(model="gemini:gemini-2.5-flash")
answer = qa.vision(
prompt="What information appears in this image?",
image_path="input.png",
)
print(answer)
Use gen_image() to create a new image, or edit_image() to remove, add, or change content in an existing image:
output_path = akasha.edit_image(
prompt="Remove the bicycle and add a green potted plant",
images="input.png",
model="openai:gpt-image-1",
save_path="edited.png",
)
print(output_path)
See the image and vision reference for multiple-image examples.
Quick start: RAG
RAG uses a local Chroma store and an embedding model selected independently from the chat model:
import akasha
rag = akasha.RAG(
model="gemini:gemini-2.5-flash",
embeddings="gemini:gemini-embedding-001",
)
answer = rag("./docs", "What are the main ideas in these documents?")
print(answer)
Typical embedding aliases include:
openai:text-embedding-3-small
gemini:gemini-embedding-001
hf:BAAI/bge-base-en-v1.5 # full installation
In light, use remote embeddings. Local HuggingFace / Sentence-Transformers embeddings require full.
Quick start: agents and tools
Agents use LangChain 1.3+ native tool calling. A custom Python function can be exposed as a tool with create_tool():
import akasha
def today_f() -> str:
return "The tool was called successfully."
today_tool = akasha.create_tool(
"Return the current date or a short status message.",
today_f,
"today_status",
)
agent = akasha.agents(
model="gemini:gemini-2.5-flash",
tools=[today_tool],
)
print(agent("Use the available tool and report its result."))
Create the agent once and reuse it for multiple questions. Rebuilding an agent for every question repeats provider initialization costs.
Streaming events
Non-streaming calls return a string. Streaming agents return JSON-serializable event dictionaries:
agent = akasha.agents(
model="gemini:gemini-2.5-flash",
tools=[],
stream=True,
thinking=True,
)
for event in agent("Explain the difference between a vector store and an embedding model."):
if event["type"] == "thinking":
print("[thinking]", event["data"])
elif event["type"] == "tool":
print("[tool]", event["data"])
elif event["type"] == "answer":
print(event["data"], end="", flush=True)
The event types are:
| Event | Meaning |
|---|---|
answer |
A chunk of the final answer |
thinking |
Provider reasoning/thinking content, when available and enabled |
tool |
A tool or Skill result |
ask(stream=True, thinking=False) currently yields text chunks. ask(stream=True, thinking=True) yields answer and optional thinking events.
Skills and MCP
Agents can load Skills from a Skill directory containing SKILL.md:
agent = akasha.agents(
model="gemini:gemini-2.5-flash",
skills=["examples/examples_skills/python-repl-skill"],
)
Skills can provide instructions, resources, and allowlisted tool bundles. Skill tools are surfaced through normal tool events.
MCP tools can be discovered with langchain-mcp-adapters, normalized with akasha.normalize_mcp_tools(), and passed to akasha.agents(tools=...). The supported transports are local stdio and remote Streamable HTTP. New integrations should use one Streamable HTTP /mcp endpoint; the older HTTP+SSE transport is deprecated.
The complete example is in examples/ex_mcp.py, with its server in examples/mcp_server.py. It uses tool_name_prefix=True when aggregating servers, preserves structured MCP results, and uses stream=False because MCP tools may be async-only.
For deterministic CI, use the local stdio fixture. Remote MCP tests must remain opt-in and should not require external credentials for the basic test suite.
Provider loading
Provider adapters are loaded when their provider is selected:
| Model alias | Adapter |
|---|---|
openai: / azure: |
langchain_openai |
gemini: |
langchain_google_genai |
anthropic: |
langchain_anthropic |
ollama: |
langchain_ollama |
Embedding adapters follow the same rule: the relevant embedding integration is loaded only when that embedding path is used. Common LangChain core modules are still shared by all providers.
Local development
Clone the repository and install it in editable mode:
git clone https://github.com/iii-org/akasha.git
cd akasha
uv venv --python 3.11
# Windows PowerShell
.venv\Scripts\Activate.ps1
uv pip install -e ".[light,dev]"
Run examples:
python examples/ex_ask.py
python examples/ex_rag.py
python examples/ex_agent.py
Testing
Unit tests do not require provider API keys:
python -m pytest tests -m unit
Image generation and editing contract tests are grouped by feature:
python -m pytest tests/vision -q
Focused agent and model tests:
python -m pytest \
tests/provider/thinking/test_thinking_config.py \
tests/agent/basic/test_core.py \
tests/provider/factory/test_import_boundaries.py
Live provider tests are opt-in because they use API quota:
$env:RUN_LLM_TESTS = "1"
$env:ENV_FILE = "tests/.env"
python -m pytest tests/agent/stream/test_live_gemini.py -q
Live tests validate provider wiring, response types, tool calling, streaming events, and RAG flow. They do not evaluate the quality of model answers.
API overview
akasha.ask(...) # document-aware QA and chat
asker.vision(...) # image understanding and visual question answering
akasha.gen_image(...) # image generation from a text prompt
akasha.edit_image(...) # edit an existing image with a text prompt
akasha.agents(...) # native tool-calling agent
akasha.RAG(...) # document ingestion and retrieval
akasha.summary(...) # map-reduce or refine summaries
akasha.MemoryManager(...) # persistent semantic memory
For detailed design decisions, upgrade notes, testing matrices, Skills, and runtime work, see dev_docs/.
License
akasha is released under the MIT License.
Release files for akasha-terminal 1.7.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| akasha_terminal-1.7.4.tar.gz | 142.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| akasha_terminal-1.7.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 321.2 kB
Release files / akasha_terminal-1.7.4.tar.gz
| Download URL | akasha_terminal-1.7.4.tar.gz |
|---|---|
| Size | 142.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
84b9910b1cfe66f471f7b48937e8ad5d97c52ef82777150670b18232e48b51ef
|
|
BLAKE2b-256 checksum How to use checksums |
8a497dacd8e6463a2edfb531a94633d0549b7f3da791801fe1d3d1f345a8f057
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / akasha_terminal-1.7.4-py3-none-any.whl
| Download URL | akasha_terminal-1.7.4-py3-none-any.whl |
|---|---|
| Size | 179.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c79ae7bc97695cf49e4d4e8e69e9e24c4dc53aa0173ff3734bea53f21f58228c
|
|
BLAKE2b-256 checksum How to use checksums |
e130f3a7f37d85661a5c78d46aa753dca97b6b0729953500e0ddecf4ac90d4ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
