DEV Community: 10XScale

We Built an AI Coding Assistant That Refuses to Finish Your Code

Mothilal M — Sun, 26 Jul 2026 15:06:19 +0000

A student finished our twelve-week backend course with near-perfect assignment scores.

In a mock interview two days later, he couldn't write a loop that summed a list of numbers. Not "wrote it inefficiently" — couldn't start. He sat there waiting for something to autocomplete.

He hadn't cheated. He'd used ChatGPT and Copilot exactly the way we all do at work: describe the problem, accept the suggestion, move on. Twelve weeks of that. Every assignment passed. Nothing learned.

That's when it clicked for us. For a working developer, an AI that finishes your code is a productivity tool. For a student, it's a machine that removes the struggle — and the struggle was the entire point.

So we built the opposite.

The rule: do the plumbing, stop at the lesson

Every coding exercise has two kinds of code in it.

There's the part that is the lesson — the recursion, the reducer, the SQL join, the async coordination. Whatever the module is actually teaching.

And there's everything else. Imports. Reading the CSV. The if __name__ == "__main__" block. Wiring up the router. Error handling around the bit that matters. Boilerplate the student has already done fifteen times, or won't be tested on, or that's just noise between them and the concept.

A tutor who does the second kind for you is helpful. A tutor who does the first kind for you is stealing your education.

So that became the rule our assistant follows:

Write the scaffolding in full. Stop dead at the learning-critical part. Say what you did and what they must finish.

In practice a response looks like this:

import csv
from collections import defaultdict

def generate_report(csv_filepath: str):
    aggregated = defaultdict(int)

    try:
        with open(csv_filepath, newline="", encoding="utf-8") as f:
            reader = csv.DictReader(f)
            for row in reader:
                # TODO(student): Implement the core aggregation logic here.
                # Each `row` is a dict like {'Category': 'A', 'Value': '100'}.
                # Update `aggregated` based on what you're reporting.
                pass

        for key, value in aggregated.items():
            print(f"{key}: {value}")

    except FileNotFoundError:
        print(f"Error: '{csv_filepath}' not found.")

I've scaffolded the CSV reader and the output formatting. You need to implement the aggregation inside the loop.

The file opens in their editor. It runs. It just doesn't do anything yet — and the one thing standing between "runs" and "works" is precisely the thing the module is teaching.

Building it on AgentFlow

We built this on AgentFlow, our own Python framework for AI agents. It's MIT licensed and on PyPI:

pip install 10xscale-agentflow

Why not LangGraph? We started there. We like the graph mental model — that part AgentFlow keeps. What we kept rebuilding by hand was everything after the graph compiled: an API server, streaming that didn't fall over, persistence that survived a restart, a TypeScript client for the frontend. And we didn't want LangChain in the dependency tree.

So AgentFlow ships the production stack in the box: graph orchestration, a REST + SSE server, a TypeScript SDK, three-layer memory (Redis cache, Postgres, vector store), native MCP, and parallel tool execution. It's LLM-agnostic — OpenAI, Gemini, Anthropic, or any OpenAI-compatible endpoint.

The tutor itself is a small graph:

from agentflow.graph import StateGraph

graph = StateGraph(TutorState(), container=container)
graph.add_node("tutor", tutor_agent)
graph.add_node("tools", tool_node)
graph.set_entry_point("tutor")

graph.add_conditional_edges("tutor", should_continue, {"tools": "tools", END: END})
graph.add_conditional_edges("tools", route_after_tools, {"tutor": "tutor"})

app = graph.compile(checkpointer=checkpointer, store=store)

The checkpointer is the part that matters more than it looks. Conversation threads live in Postgres, so a student can close the laptop mid-exercise, come back the next evening, and the tutor still knows which milestone they're stuck on and what they already tried. No re-explaining.

The interesting bit: the agent's hands are in your editor

Here's the architectural problem. The agent runs on our server. The student's code lives in their editor. How does a model on a server read a selection, or write a file, or highlight the three lines where the bug is?

AgentFlow solves this with remote tools, and it's my favourite feature in the framework.

You register a tool from the client — in our case, the VS Code extension:

client.registerTool({
  node: 'tools',
  name: 'read_code',
  description: "Read the student's code. Use want='selection' for what they've " +
               "highlighted, 'error_context' for the file plus last terminal output.",
  parameters: {
    type: 'object',
    properties: {
      want: { type: 'string', enum: ['file', 'selection', 'range', 'error_context'] },
    },
    required: ['want'],
  },
  handler: async (args) => {
    // runs inside VS Code, with the full editor API available
    const editor = vscode.window.activeTextEditor;
    return editor.document.getText(editor.selection);
  },
});

await client.setup();   // publishes the schemas to the server

The model sees the tool schema and calls it like any other tool. But the server doesn't execute it — it returns a RemoteToolCallBlock, the SDK spots it, runs your handler in the editor, and sends the result back as a tool message. The graph picks up exactly where it left off.

The model gets eyes and hands inside VS Code without a single line of code leaving the student's machine unless the agent explicitly asks for it. No shipping the whole file on every message. No stale context.

The same mechanism drives the writing side — write_file, highlight, open_file, propose_edit. The agent decides what should happen; the editor decides how.

The pedagogy is a markdown file, not an if-statement

The thing I'd most want another team to steal: none of the teaching rules live in Python.

AgentFlow has a skills system — playbooks in markdown, loaded per turn based on what the student is doing. Ours reads like guidance to a human tutor:

## The Hardest-Part Boundary

Learning-critical core -> coach, never solve.
Boilerplate and plumbing -> write it freely.

Milestone is "fetch and display data"?
  - Stuck on the fetch -> that IS the lesson. Scaffold around it, hand it back.
  - Stuck on the loading spinner CSS -> not the lesson. Just write it.

## Understanding Gate

Before marking anything complete, ask WHY they chose their approach.
Ask what happens at [edge case]. Passing tests is not understanding.

Our instructional designers edit that file. They don't open a Python file, they don't wait for a deploy, they don't file a ticket. When a cohort struggles with a module, the person who understands why changes the rules directly.

That separation — orchestration in code, pedagogy in markdown — has been worth more than any individual feature.

Measuring who actually wrote the code

Here's the part I think most AI-in-education tools are missing.

If your AI can write code into a student's file, you have created a brand new way to cheat, and you have an obligation to measure it. Otherwise "completed the assignment" becomes meaningless.

So every AI-originated edit in our extension goes through exactly one function, and that function records the event before it writes:

async function applyBlock(block) {
  record('ai_applied', block.file, block.code.length);   // ledger first
  await vscode.workspace.fs.writeFile(target, buffer);   // then the write
}

Student keystrokes get counted from onDidChangeTextDocument. The ratio between them is displayed live in the panel header — a small typed 78% badge that both the student and their trainer can see.

Two hard-won lessons on this:

It has to be a single choke point. The moment one code path writes to a file without going through it, the number silently becomes fiction — and a fiction that looks like data is worse than no data.

Build it on day one. You cannot retrofit authorship tracking. The edits you didn't record are gone forever.

A high AI-ratio isn't automatically bad, by the way. It's a signal. It tells the tutor to probe harder before marking a milestone complete, and it tells a trainer which students to check on before the mock interview, not after.

What we've seen so far

[FILL IN — replace this section with your own numbers before publishing.]
Good things to include if you have them: how many students are using it, change in
mock-interview pass rate, average authorship ratio per module, or a direct student
quote. If you don't have hard data yet, say so plainly — "we're one cohort in and
still collecting data" is more credible than a number you can't defend, and readers
on dev.to will absolutely ask.

Try it

AgentFlow is open source and MIT licensed:

GitHub: github.com/10xHub/Agentflow
Docs: 10xhub.github.io/agentflow-docs
Install: pip install 10xscale-agentflow 10xscale-agentflow-cli

If you're building anything that puts an AI inside an editor, the remote-tools pattern is worth an hour of your time even if you use a different framework entirely. Being able to run a tool handler in the client while the graph stays on the server unlocks a category of product that's genuinely painful to build otherwise.

The question I keep going back and forth on: should a student be able to override the tutor and just get the full answer? There's a real argument that fighting a tool teaches nothing but resentment, and adults should get to choose. There's an equally real argument that the override becomes the default within a week.

We landed on "no override, but unlimited explanations." I'm genuinely not certain we got it right. What would you have done?

AgentFlow — From Agent Code to Production API in Minutes

Shudipto Trafder — Sun, 03 May 2026 17:09:58 +0000

AgentFlow — The Python Framework for Production AI Agents

Stop rebuilding the same agent infrastructure. AgentFlow gives you auth, streaming, persistence, and a React frontend — out of the box.

AgentFlow (10xscale-agentflow on PyPI) is an open-source Python framework for building and deploying multi-agent AI systems. Write your agent graph once. Run it locally. Ship it to production without rewriting your backend.

Built by 10xScale. MIT licensed. No vendor lock-in.

Why AgentFlow?

Most agent frameworks stop at the prototype. You get a cute demo, then spend weeks bolting on auth, rate limiting, persistence, and a frontend. AgentFlow is built for what comes after the demo.

One framework. From first pip install to production Docker deploy.

🔗 Links

Resource	URL
Core Python Library	github.com/10xHub/Agentflow
API & CLI	github.com/10xHub/agentflow-cli
Documentation	10xhub.github.io/agentflow-docs
PyPI — Core	pypi.org/project/10xscale-agentflow
PyPI — CLI	pypi.org/project/10xscale-agentflow-cli

The Full Stack

agentflow            →  Core Python orchestration engine
agentflow-cli        →  FastAPI server + CLI tooling
agentflow-client     →  TypeScript/React SDK (@10xscale/agentflow-client)
agentflow-playground →  Hosted UI for testing agents

Use any layer alone. Use them together for a complete AI product stack — from LLM call to browser UI — without stitching four different libraries together.

Get Running in 60 Seconds

pip install 10xscale-agentflow-cli

agentflow init   # scaffold a new project
agentflow api    # start the dev server
agentflow play   # open the playground UI

That's it. Your agent is running, streamed, and explorable in under a minute.

What You Get

Graph-Based Agent Orchestration

AgentFlow uses a StateGraph — directed nodes, conditional edges, and full control over execution flow. No black boxes. No magic routing you can't debug.

from agentflow.graph import Agent, StateGraph, ToolNode
from agentflow.state import AgentState, Message
from agentflow.utils.constants import END

def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"The weather in {location} is sunny, 72°F"

graph = StateGraph()
graph.add_node("MAIN", Agent(
    model="gemini/gemini-2.5-flash",
    system_prompt=[{"role": "system", "content": "You are a helpful assistant."}],
    tool_node_name="TOOL"
))
graph.add_node("TOOL", ToolNode([get_weather]))

def route(state: AgentState) -> str:
    if state.context and state.context[-1].tools_calls:
        return "TOOL"
    return END

graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
graph.add_edge("TOOL", "MAIN")
graph.set_entry_point("MAIN")

app = graph.compile()
result = app.invoke(
    {"messages": [Message.text_message("Weather in NYC?")]},
    config={"thread_id": "1"}
)

Stateful. Tool-calling. Under 30 lines.

LLM-Agnostic

Pass the model string. AgentFlow routes it.

Provider	Package
OpenAI (GPT-4o, o3, etc.)	`pip install openai`
Google Gemini + Vertex AI	`pip install google-genai`
Anthropic Claude	`pip install anthropic` (coming soon)

No provider-specific abstractions to learn. Swap models without touching your agent logic.

Parallel Tool Execution — Automatic

When an LLM calls multiple tools at once, AgentFlow runs them concurrently. No config required.

Other frameworks:  1.0s + 1.5s + 0.8s = 3.3s
AgentFlow:         max(1.0s, 1.5s, 0.8s) = 1.5s  ⚡ 2.2x faster

Production Memory — Three Layers

Working Memory    →  Current execution state (AgentState)
Session Memory    →  Redis (hot) + PostgreSQL (durable) checkpointer
Knowledge Memory  →  Qdrant vector store + Mem0 semantic recall

Redis keeps hot conversation state fast. PostgreSQL keeps it durable and horizontally scalable. Both run together — you don't pick one.

Streaming

stream_gen = app.astream(
    inp,
    config=config,
    response_granularity=ResponseGranularity.LOW,
)
async for chunk in stream_gen:
    print(chunk.model_dump())

Three granularity levels: token-by-token (ChatGPT-style), message-by-message, or node-by-node graph traces. Your frontend decides what to show.

Auth and Security — Built In, Not Bolted On

Most frameworks leave auth as an exercise for the reader. AgentFlow ships it.

{ "auth": "jwt" }
{ "auth": null }
{ "auth": { "method": "custom", "path": "auth.my_backend:MyAuth" } }

One line in agentflow.json. Switch from dev to production auth without touching your graph code.

Security features included:

JWT authentication with configurable secrets
Custom auth backends for OAuth2, API keys, and sessions
Role-Based Access Control (RBAC)
Sliding-window rate limiting (memory or Redis backends)
Configurable request size limits (DoS protection, default 10 MB)
Auto-redaction of tokens and secrets from logs
Startup validation — warns about insecure CORS and debug mode before you accidentally deploy them

Lifecycle Callbacks

Hook into every layer of execution — before and after each LLM call, tool call, or MCP invocation. Hook into the graph itself for start, end, checkpoint, interrupt, resume, and error events.

Use them for audit logs, billing meters, policy enforcement, prompt-injection checks, or any business logic that shouldn't live inside the prompt.

The CLI

agentflow init              # scaffold project + config
agentflow api               # dev server with auto-reload
agentflow play              # open playground against local backend
agentflow build --docker-compose  # generate Dockerfile + compose

Auto-generated FastAPI endpoints:

Endpoint	Method
`/invoke`	POST — synchronous agent call
`/stream`	POST — streaming agent call
`/threads`	GET — list conversation threads
`/threads/{id}`	GET — fetch thread history
`/threads/{id}`	DELETE — delete thread

Your agent graph becomes a production API. No FastAPI boilerplate to write.

Dependency Injection with InjectQ

from agentflow.utils import tool

@tool(tags=["weather"])
async def get_weather(location: str, user_id: str = Inject(UserService)) -> str:
    """Get weather for a location."""
    return f"Weather for user {user_id} in {location}: sunny"

Clean tools. Testable tools. Per-request context without global state.

Human-in-the-Loop

Pause execution mid-graph. Inject a human decision. Resume with full state intact. No re-running prior steps.

Approval workflows, moderation gates, interactive debugging — all supported without custom state management.

Event Publishing

Publisher	Use Case
Redis Pub/Sub	Lightweight in-process distribution
Kafka	High-volume event streaming
RabbitMQ	Reliable queuing, distributed systems
Console	Local debugging
Custom	Any backend you want

React/TypeScript Client SDK

@10xscale/agentflow-client gives you React hooks (useAgent, useStream, useThreads), token-level streaming for ChatGPT-style UIs, and client-side tool execution. The frontend talks to your AgentFlow API without custom integration code.

Feature Comparison

Feature	AgentFlow	LangGraph	CrewAI	AutoGen
Architecture	Graph	Graph	Role-Based	Conversational
Full Stack (Backend + Frontend SDK)	✅	❌	❌	❌
Parallel Tool Execution	✅ Auto	⚠️ Config	❌	❌
Persistence	✅ Redis + Postgres	⚠️ Postgres/SQLite	⚠️ Local	⚠️ Local
Dependency Injection	✅ Native	❌	❌	❌
CLI + Docker Deployment	✅ One command	❌	❌	❌
Auth Built-In	✅ JWT + Custom	❌	❌	❌
Rate Limiting	✅ Memory + Redis	❌	❌	❌
Lifecycle Callbacks	✅ Full	⚠️ Manual	❌	⚠️ Manual
MCP Support	✅ Native	⚠️ Partial	❌	❌
Event Publishing	✅ Kafka/Redis/AMQP	❌	❌	❌
Open Source (MIT)	✅	✅	✅	✅

Installation

# Core library
pip install 10xscale-agentflow

# Full CLI + API server
pip install 10xscale-agentflow-cli

Optional extras:

pip install 10xscale-agentflow[pg_checkpoint]   # PostgreSQL + Redis persistence
pip install 10xscale-agentflow[mcp]             # Model Context Protocol
pip install 10xscale-agentflow[google-genai]    # Google GenAI adapter
pip install 10xscale-agentflow[kafka]           # Kafka event publishing
pip install 10xscale-agentflow[redis]           # Redis publisher + rate limiting

Current Version

Package	Version
`10xscale-agentflow` (core)	v0.7.4
`10xscale-agentflow-cli`	v0.3.2

Added in v0.7.x: multimodal support (images, audio, video), extended reasoning / chain-of-thought, 3-layer memory, callback and lifecycle hooks, agent skills, Vertex AI support, structured Pydantic outputs.

Roadmap

✅ Graph engine with nodes, edges, and conditional routing
✅ Redis + PostgreSQL state checkpointing
✅ Tool integration — local Python, MCP, optional adapters
✅ Parallel tool execution
✅ Lifecycle callbacks and graph hooks
✅ Streaming + event publishing
✅ Human-in-the-loop
✅ Multimodal agents
🚧 Remote node execution for distributed processing
🚧 OpenTelemetry tracing
🚧 More persistence backends (DynamoDB, etc.)
🚧 Visual graph editor

Privacy and Licensing

MIT License — use freely in commercial products
No data collection — your conversations and agent data stay on your infrastructure
No per-call billing — you pay for your LLM API and infra, not our licensing
Deploy anywhere — Docker, Kubernetes, AWS ECS, Cloud Run, Azure, Heroku

Links


Core Library	https://github.com/10xHub/Agentflow
API & CLI	https://github.com/10xHub/agentflow-cli
Documentation	https://10xhub.github.io/agentflow-docs
PyPI Core	https://pypi.org/project/10xscale-agentflow/
PyPI CLI	https://pypi.org/project/10xscale-agentflow-cli/
Issues & Requests	https://github.com/10xHub/Agentflow/issues
Discussions	https://github.com/10xHub/Agentflow/discussions

Built by 10xScale and the community. MIT licensed.

We Built a Typesense Dashboard with an AI Brain and It's Lowkey Insane 🧠⚡

Mothilal M — Sat, 28 Feb 2026 16:56:37 +0000

TLDR for the scroll-addicted 📱

We built Typesense UI — an open-source, fully interactive dashboard for Typesense with a built-in AI assistant powered by Gemini 2.0 Flash. You can literally talk to your search data in plain English.

It's free. It's open source. It slaps.

👉 GitHub: github.com/Mothilal-hire10x/typesense-ui
👉 Run it instantly: npx typesense-ui

The Origin Story (a.k.a. why we rage-built this) 😤

If you've ever used Typesense, you know it's an absolute beast of a search engine — blazingly fast, typo-tolerant, and open source. But let's be real... managing collections and documents through cURL commands and JSON payloads?

That's giving 2015 energy.

We wanted something that looks like it belongs in 2026. Something with dark mode (obviously), smooth animations, and — here's the plot twist — an AI that actually understands our data and can query it for us.

So we built it. And honestly? It ate and left no crumbs. 🍽️

What Makes This Different? (It's Not Just Another CRUD App)

🤖 AI Assistant That Actually Understands Your Data

This is the main character energy of the whole project.

The built-in AI chat (powered by Gemini 2.0 Flash) doesn't just answer generic questions — it has full Typesense tool-calling capabilities. It can:

List and inspect your collections
Search documents with complex filters
Create, update, and delete documents
Show results in beautifully formatted tables
Ask for confirmation before destructive operations (it's responsible bestie fr fr)

Just type something like:

"Show me all users who signed up last month sorted by name"

And it literally queries your Typesense instance and returns the results. In a table. With pagination. WHAT.

⚡ The Landing Page Goes STUPID Hard

Not gonna lie, we may have gone a little overboard with the landing page. It features:

3D scene built with React Three Fiber & Three.js
GSAP animations with scroll-triggered reveals
Lenis smooth scrolling (that butter-smooth feel)
Magnetic hover effects on CTAs
Fully responsive, dark-themed, cinematic vibes

It's giving Apple product page energy and we're not apologizing for it.

🎨 The Dashboard Itself (Where the Real Work Happens)

Once you connect to your Typesense server, you get:

Feature	What It Does
Collections Sidebar	Browse all collections with doc counts, search/filter
Advanced Table View	Paginated, sortable, with column picker
Live Search	Instant full-text search across all fields
Dynamic Filters	Auto-generated from schema — text, range, boolean
Document Editor	Create, edit, delete docs with JSON editor
Dark/Light Mode	Because we respect the vibe check
Schema Inspector	View full collection schemas at a glance

Everything is real-time. Type a search query, toggle a filter, click a column header — instant response. No loading spinners holding your life hostage.

How to Get Started (It's Embarrassingly Easy)

Option 1: The One-Liner 🏎️

npx typesense-ui

That's it. That's the tweet. It spins up a local server and opens the dashboard. Done.

Option 2: Clone & Vibe

git clone https://github.com/Mothilal-hire10x/typesense-ui.git
cd typesense-ui
npm install
npm run dev

Open http://localhost:3000, enter your Typesense server details, and you're locked in. 🔐

Option 3: Install Globally

npm install -g typesense-ui
typesense-ui

Setting Up the AI Assistant

Click the ✨ sparkle button in the bottom-right
Enter your Gemini API key (get one free here)
Start chatting with your data like it owes you money

The AI in Action — Some Wild Prompts That Just Work

Here are some things you can literally just say to the AI:

🗣️ "What collections do I have?"
→ Lists all collections with doc counts and schemas

🗣️ "Find products cheaper than $50 sorted by price"
→ Searches with filter_by and sort_by, returns a formatted table

🗣️ "Delete the document with ID abc123 from the users collection"
→ Shows a confirmation dialog first (safety first bestie)

🗣️ "What fields does the orders collection have?"
→ Returns the full schema breakdown

🗣️ "Create a new document in products with name 'Widget' and price 29.99"
→ Creates the doc after your confirmation

The AI has function calling — it doesn't just hallucinate answers, it actually executes real Typesense operations. It's like having a senior dev who never sleeps and never complains. We love to see it.

Why Typesense Deserves Better Tooling

Typesense is genuinely one of the best open-source search engines out there. It's:

⚡ Blazingly fast (sub-millisecond searches)
🔤 Typo-tolerant out of the box
🧠 Easy to setup compared to Elasticsearch
💰 Free & open source

But the ecosystem around it — especially for visual management — has been lacking. The official dashboard is decent, but we wanted something that feels modern, powerful, and has AI baked in.

Typesense UI is our attempt to give Typesense the visual experience it deserves.

What's Next? 🔮

Some things on the roadmap:

[ ] Multi-server support — switch between Typesense instances
[ ] Collection creation wizard — visual schema builder
[ ] Export/Import — bulk operations with CSV/JSON
[ ] Query playground — test search queries with syntax highlighting
[ ] Analytics dashboard — search metrics and insights
[ ] More AI models — OpenAI, Claude, local LLMs

If any of these get you hyped, drop a ⭐ on the repo and open an issue with your ideas!

Show Some Love ❤️

If this project saved you time, made you smile, or just impressed you a little bit:

⭐ Star the repo: github.com/Mothilal-hire10x/typesense-ui
🐛 Report bugs: Issues
🤝 Contribute: PRs are always welcome!
📢 Share this post: Help other devs discover it

Wrapping Up

Building this was genuinely one of the most fun projects we've worked on. The intersection of search technology, modern frontend, and AI is such a vibe right now, and we think we're only scratching the surface.

If you're using Typesense (or thinking about it), give Typesense UI a spin. It's free, it's open source, and it might just change how you interact with your search data.

Now go touch some grass. Or don't. We're not your mom. 🌱

Built with React, TypeScript, and an unhealthy amount of caffeine ☕

Follow us for more open-source drops and dev content that doesn't put you to sleep.

Stop Wiring Dependencies by Hand - Meet InjectQ, Python DI Done Right

Mothilal M — Sun, 22 Feb 2026 12:36:40 +0000

You've been there.

A service that needs a database, which needs a config, which needs an env variable that someone hardcoded three months ago and nobody remembers where. You're passing objects down ten layers of constructors. Testing means faking half your app.

It's messy. And it doesn't have to be.

Dependency Injection is the fix - but most Python DI libraries feel like they were designed for a different language. Overly complex, decorator-heavy, or magical in ways that make debugging a nightmare.

So we built InjectQ.

"We wanted DI that feels like Python - not like a Java framework that got lost on its way to PyPI."

What is InjectQ?

InjectQ is a modern, lightweight Python dependency injection library focused on:

✅ Clarity and simplicity
✅ Type safety (works with mypy, pyright)
✅ Async-first APIs
✅ Seamless FastAPI & Taskiq integration
✅ Production-grade performance (270ns per bind)

Links:

📦 PyPI
🐙 GitHub
📖 Docs

Install in one line

pip install injectq

For framework integrations:

pip install injectq[fastapi]   # FastAPI support
pip install injectq[taskiq]    # Taskiq support

Quick Start - Zero config, maximum clarity

from injectq import InjectQ, inject, singleton

container = InjectQ.get_instance()

# Bind a value — dict-style, no ceremony
container[str] = "Hello, World!"

@singleton
class UserService:
    def __init__(self, message: str):
        self.message = message

    def greet(self) -> str:
        return f"Service says: {self.message}"

@inject
def main(service: UserService) -> None:
    print(service.greet())

main()  # → Service says: Hello, World!

That's it. @singleton = one instance app-wide. @inject = auto-resolve from type hints. No XML, no 500-line config, no magic.

Core Features

🔧 Dict-like API

The simplest mental model possible:

from injectq import InjectQ

container = InjectQ.get_instance()

# Bind anything
container[str] = "config_value"
container[Database] = Database()

# Retrieve
db = container[Database]

🎯 Decorator + Type-based Injection

@inject
def process(service: UserService, db: Database):
    # Both auto-resolved from the container
    ...

Also supports Inject[T] for inline type annotations that work with static type checkers.

🔄 Scopes and Lifetimes

from injectq import singleton, transient, scoped

@singleton
class Database: ...       # One instance, lives forever

@transient
class Validator: ...      # New instance every resolution

@scoped("request")
class RequestContext: ... # One per request scope

# Async scopes work too
async with container.scope("request"):
    ctx1 = container.get(RequestContext)
    ctx2 = container.get(RequestContext)
    assert ctx1 is ctx2  # Same instance ✓

🆕 Hybrid Factories - The Feature That Changes Everything

This is new in v0.4 and it's genuinely great.

The problem: You have a factory that needs a database (DI-managed) and a user ID (runtime value). Old way is verbose:

# ❌ Old way — manually resolve everything
db    = container[Database]
cache = container[Cache]
svc   = container.call_factory("user_service", db, cache, "user123")

New way with invoke():

def create_user_service(db: Database, cache: Cache, user_id: str):
    return UserService(db, cache, user_id)

container.bind_factory("user_service", create_user_service)

# ✅ Auto-inject db and cache, you only pass what you know
svc = container.invoke("user_service", user_id="user123")

# Async version
svc = await container.ainvoke("async_service", batch_size=100)

InjectQ resolves what it knows from the container. You provide only the runtime-specific values. Clean.

🚀 FastAPI Integration

from typing import Annotated
from fastapi import FastAPI
from injectq import InjectQ, singleton
from injectq.integrations.fastapi import setup_fastapi, InjectFastAPI

app       = FastAPI()
container = InjectQ.get_instance()
setup_fastapi(container, app)

@singleton
class UserService:
    def get_user(self, user_id: int) -> dict:
        return {"id": user_id}

@app.get("/users/{user_id}")
async def get_user(
    user_id: int,
    user_service: Annotated[UserService, InjectFastAPI(UserService)],
):
    return user_service.get_user(user_id)

🧪 Testing — Mocking Without the Pain

from injectq.testing import override_dependency, test_container

# Override a specific dep for the duration of a block
with override_dependency(Database, MockDatabase()):
    service = container.get(UserService)
    # UserService gets MockDatabase here ✓

# Fully isolated test container — no global state bleed
with test_container() as tc:
    tc.bind(Database, MockDatabase)
    # Clean slate for each test

Pro tip: Use InjectQ.test_mode() with pytest fixtures to auto-reset your container between tests.

🏗️ Modules and Providers

For larger apps, organize your bindings into modules:

from injectq.modules import Module, SimpleModule, ProviderModule, provider

class AppModule(Module):
    def configure(self, binder):
        binder.bind(Config, Config())
        binder.bind(Database, Database)

class Providers(ProviderModule):
    @provider
    def make_notifier(self, db: Database, cfg: Config) -> Notifier:
        return Notifier(db, cfg)

container = InjectQ(modules=[AppModule(), Providers()])

🛡️ Abstract Class Validation

InjectQ validates at bind time, not at resolution time:

from abc import ABC, abstractmethod
from injectq.utils.exceptions import BindingError

class PaymentProcessor(ABC):
    @abstractmethod
    def process_payment(self, amount: float) -> str: ...

# ❌ Raises BindingError immediately — no surprises at runtime
container.bind(PaymentProcessor, PaymentProcessor)

# ✅ Correct — bind the concrete implementation
container.bind(PaymentProcessor, CreditCardProcessor)

Fail fast. Debug less.

Performance Benchmarks

InjectQ isn't just clean — it's fast.

Operation	Speed
Basic bind / get	270–780 nanoseconds
Dependency resolution	~1 microsecond
10-service web request simulation	142 microseconds
1,000+ concurrent operations	Sub-millisecond

Thread-safe by default. Production-ready from day one.

Why InjectQ Over Alternatives?

Feature	InjectQ	dependency-injector	injector
Dict-like API	✅	❌	❌
FastAPI integration	✅ Built-in	✅	❌ Manual
Hybrid factories (invoke)	✅	❌	❌
Async scope contexts	✅	⚠️ Limited	❌
Testing utilities	✅ Built-in	✅	❌ Manual
Taskiq integration	✅	❌	❌
Abstract class guard	✅ Bind-time	❌ Runtime	❌ Runtime

TL;DR

If you're tired of:

Manually wiring dependencies
Global state leaking into tests
Framework integrations that require 200 lines of glue code

InjectQ is for you.

pip install injectq

Built with ♥ by the 10xHub team. MIT Licensed. Contributions welcome.

Have questions or feature requests? Drop them in the comments or open an issue on GitHub. We read everything.